Imagine how much time you would waste driving in a city where road signs looked like the one on the right.If software development is like driving a car then comments are road signs along the way.
Comments are purely informational and do NOT affect the final machine code.
A good comment is
one that reduces the development life cycle for the next developer that drives
down the road.
A bad comment is
one that increases the development life cycle for any developer unfortunate
enough to have to drive down that road.
Sometimes that next unfortunate driver will be you several years later!
I know most developers are hardwired to automatically assume that comments are a good thing. I'd be interested in hearing from anyone who has never experienced the problems below...
Sometimes that next unfortunate driver will be you several years later!
I know most developers are hardwired to automatically assume that comments are a good thing. I'd be interested in hearing from anyone who has never experienced the problems below...
Comments do not Necessarily Increase Development Speed
I was in university in 1985 and one of my professors presented a paper (which I
have been unable to locate) of a study done in the 1970s. The study took a software program, introduced defects
into it, and then asked several teams to find as many defects as they could.
The interesting part of the study was that 50% of the teams had the comments completely removed from the source code. The result was that the teams without comments not only found more defects but also found them in less time.
The interesting part of the study was that 50% of the teams had the comments completely removed from the source code. The result was that the teams without comments not only found more defects but also found them in less time.
So unfortunately, comments can serve as weapons of mass distraction…
Bad comments
A bad comment is one that wastes your time and does not help
you to drive your development faster.
Let's go through the categories of really bad comments:
- Too many comments
- Excessive history comments
- Emotional and humorous comments
Too many comments
are a clear case of where less is more.
There are programs with so many comments that it obscures the code. Some of us have worked on programs where
there were so many comments you could barely find the code!
History comments make some sense, but then again isn't that
what the version control comment is for?
History comments are questionable when you have to page down multiple
times just to get to the beginning of the source code. If anything, history comments should be moved
to the bottom of the file so that Ctrl-End actually takes you to the bottom of
the modification history.
We have all run across comments that are not relevant. Some comments are purely about the
developer's instantaneous emotional and intellectual state, some are about how
clever they are, and some are simply attempts at humor (don't quit your day job!).
Check out some of these gems (more can be
found here):
//Mr. Compiler, please do not read this.
// I am not sure if we need this, but too scared to delete.
//When I wrote this, only God and I understood what I was doing
//Now, God only knows
// I am not responsible of this code.
// They made me write it, against my will.
// I have to find a better job
try { ... }
catch (SQLException ex)
{ // Basically, without saying too much, you're screwed. Royally and totally. } catch(Exception ex)
{ //If you thought you were screwed before, boy have I news for you!!! }
// Catching exceptions is for communists
// If you're reading this, that means you have been put in charge of my previous project.
// I am so, so sorry for you. God speed.
// if i ever see this again i'm going to start bringing guns to work
//You are not expected to understand this
Use Self-Documenting Code
When observations of the final program disagree with the
requirements model we have a defect which leads us to change our machine code model.
Of course we don't alter the machine code model directly (at least most of us); we
update the source code which is the only real model. Since comments are not compiled into the
machine code there is some logic to making sure that the source code
model be self-documenting.
Code is the only model that really counts!
Code is the only model that really counts!
Self-documenting code
requires that you choose good names for variables, classes, function names, and
enumerated types. Self-documenting means
that OTHER developers can understand what you have done. Good self-documenting code has the same
characteristic of good comments; it decreases the time it takes to do
development. Practically, your code is self-documenting when your peers say that it is, not when YOU say that it is. Peer reviewed comments and code is the only way to make sure that code will lead to faster development cycles.
Comments gone Wild
Even if all the comments in a program are good (i.e. reduce
development life cycle) they are subject to drift over time. The speed of software development makes it difficult to make sure that comments stay in alignment with the source code.
Comments that are allowed to drift become road signs that are no longer relevant to drivers.
Good comments go wild when the developer is so focused on
getting a release out that he does not stop to maintain comments. Comments have gone wild when they become misaligned with the source code; you have to terminate them.
No animals (or comments) were harmed in the writing of this blog.
Commented Code
Code gets commented during a software release as we are
experimenting with different designs or to help with debugging. What is really not clear is why code remains
commented before the final check-in of a software release.
Just in case what?
At the end of a software release you have already established that you are not going to use your commented code, so why are you dragging it around? People hang on to commented code as if it is a “Get Out of Jail Free” card, it isn't.
The reality is that commented code can be a big distraction. When you leave commented code in your source code you are leaving a land mine for the next developer that walks through it.
When the pressure is on to get defects fixed developers will
uncomment previously commented code to see if it will fix the problem. There is no substitute for understanding the
code you are working on – you might get lucky when you reinstate commented code; in all likelihood it will blow up in your face.
Solutions
Time spent on writing self-documenting code will help you
and your successors reduce development life cycles. It is absolutely false to believe that you do
not have time to write self-documenting code.
If you are going to take on the hazards of writing comments then they need to be peer reviewed to make sure that OTHER developers understand the code. Unless the code reviewer(s) understands all the comments the code should not pass inspection.
If you don't have a code review process then you are only
commenting the code for yourself. The
key principle when writing comments is Non Nobis Solum (not for ourselves alone).
When you see a comment that sends you on a wild goose
chase – fix it or delete it.
If you are the new guy on the team and realize that the comments are wasting your time – get rid of them; your development speed will go up.
If you are the new guy on the team and realize that the comments are wasting your time – get rid of them; your development speed will go up.
Articles on Comments by Other People
Other Sources of Amusement
Other articles in the "Loser" series
 |
| Moo? |
Want to see more sacred cows get tipped? Check out
- Comments are for Losers
- Efficiency is for Losers
- Debuggers are for Losers
- Testing departments are for Losers
software development company to outsource the work to is a daunting task. Software development is infamous for project slippage, even by the big names in the industry.
ReplyDeleteGood one!! Even I agree with you that bad commenting will rather increase the development life cycle. However I fell that commenting is essential at-least for documentation purpose only when it is used in a professional and efficient manner.
ReplyDeleteAs long as comments are kept current there is no problem. Every code review process should check comments to make sure that they are not drifting out of sync with the code.
ReplyDelete