Win a copy of The Java Performance Companion this week in the Performance forum!
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

Clean Code: A Handbook of Agile Software Craftsmanship - comments in code

 
seema prakash
Ranch Hand
Posts: 59
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Writing Comments: I definitely believe writing descriptive comments makes it easier for the developer to understand at a glance what is going on in the code easily especially when the code is complex. Do you agree ?
[ September 23, 2008: Message edited by: Ilja Preuss ]
 
Ilja Preuss
author
Sheriff
Posts: 14112
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Personally, I find that almost every piece of complex code can be refactored so that it doesn't need comments to be easily understood. Almost everything you can write in comments can as well be expressed in method and variable names, as far as I can tell. (Just today I named a method for an Eclipse plugin "badHackForTheShortPeriodOfTimeInWhichWeCantTellWhetherATestHasAlreadyBeenStarted()". It was basically a Thread.sleep that I extracted into its own method.)
 
seema prakash
Ranch Hand
Posts: 59
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Yes, I agree that the complex code has to be refactored and the method names and variable names should be descriptive enough.

What about the comments we add after fixing a bug ? Is it not a good practice to do that ? If we have nested loops, then it is easier to have some comment such as "//end of if". What about such comments?
 
Paul Croarkin
Ranch Hand
Posts: 106
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I agree with Ilja. Re-factoring to smaller methods makes code much more readable. Of course comments should be included for things that will be difficult for a future maintainer to understand.

I lump comments in with other artifacts. Generate as few artifacts as are needed to get the job done in a professional manner.

Setter / Getter comments are almost always a compete waste of time. But a comment that explains some difficult mathematical equation is always appreciated. I think that after you have coded every day for years, you get a pretty good feeling as to what is necessary.
 
Jeanne Boyarsky
author & internet detective
Marshal
Posts: 34672
367
Eclipse IDE Java VI Editor
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Originally posted by seema prakash:
If we have nested loops, then it is easier to have some comment such as "//end of if". What about such comments?

If the method is so long/complex that it isn't immediately obvious what braces go with what, it should be refactored to be more readable.

I try for reducing comments in favor of code as a goal. I don't think I've gone as far as Ilja yet . I think the place for comments is for when explaining something non-obvious or likely to introduce a bug. Like "we have to check for ___________ because the legacy system does it that way." I'm also a fan of TODO comments when accompanied by a specific time to be done (otherwise they tend to stay forever.) For example we have a couple "//TODO change this to use varargs when we move to Java 5", "//TODO this code can be removed on or after ____________" and the like floating around.
 
Katrina Owen
Sheriff
Posts: 1367
18
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I find that in certain instances comments can be helpful - usually this is to comment some trade-off or gotcha that isn't immediately available in the code.

Most of the time, though, I find that comments just clutter things up, either by being wrong, or stating the obvious, or getting in the way of the flow of the code.

As for

type comments - what Ilja and Jeanne said! If you are having trouble matching blocks and braces, extract bits and pieces with well-named methods.

Robert Martin suggests in 'Clean Code' that your code should read like a newspaper article.

And then he explains how to go about doing that.
 
Ilja Preuss
author
Sheriff
Posts: 14112
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Originally posted by Jeanne Boyarsky:

I think the place for comments is for when explaining something non-obvious or likely to introduce a bug. Like "we have to check for ___________ because the legacy system does it that way."


I wonder whether this could be done using a test...
 
Alaa Nassef
Ranch Hand
Posts: 471
Hibernate Mac OS X Spring
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Originally posted by Jeanne Boyarsky:

I don't think I've gone as far as Ilja yet


I don't think anybody has gone as far as Ilja yet . Just kidding. As for the "//end if" style comments, since I recently had a bad experience with code that we got from another company, with a method having around 850 lines of code (excluding the white spaces, braces & comments), PLEASE refactor your code to short methods that can be readable, maintainable and testable, rather than using comments that specify the beginning and end of each section.
 
Jeanne Boyarsky
author & internet detective
Marshal
Posts: 34672
367
Eclipse IDE Java VI Editor
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Originally posted by Ilja Preuss:
I wonder whether this could be done using a test...

Probably. But the point is to call attention to it in the code, not just the test. Where I work, people read the code before the tests.
 
Ilja Preuss
author
Sheriff
Posts: 14112
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Originally posted by Jeanne Boyarsky:

Probably. But the point is to call attention to it in the code, not just the test. Where I work, people read the code before the tests.


Me too. So without the comment, I might only get feedback when I've already made the change. I'm not sure I'm deeply troubled by that thought. Mhh...
 
Jeff Langr
author
Ranch Hand
Posts: 799
5
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I have the same thought about comments as with "# of lines per method"--try to find a way to write fewer.

Comments are a concession that says: "I couldn't figure out how to write the code clean enough, so here's something that explains it." One of the goals of Clean Code is to show you a style that will help you achieve this goal.

I find that too many comments become lies to waste time trusting them.

I don't believe that there's such a thing as "self-documenting code," however. For that, you need tests that describe how the well-structured production code gets used.

Jeff
 
Robert Martin
Author
Ranch Hand
Posts: 76
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Originally posted by seema prakash:
Writing Comments: I definitely believe writing descriptive comments makes it easier for the developer to understand at a glance what is going on in the code easily especially when the code is complex. Do you agree ?

[ September 23, 2008: Message edited by: Ilja Preuss ]


I think it would be better if the code were not complex. I think it would be better if the code was understandable at a glance. I think the effort of writing a comment for complex code is misplaced. The effort should be expended on making the code simpler and easier to understand.

Most comments are lies. They don't start out to be lies, but gradually the get out of date. You might say that developers should be disciplined enough to maintain the comments; but this is not reasonable. Comments have no detectable binding to what they describe. If you modify a function, you have no way of knowing that 1000 lines above you (or perhaps in a different file) there is a comment that contradicts what you are doing). So comments slowly degrade and turn into misinformation.

Who hasn't seen a comment that was just plain wrong. Who hasn't seen a comment that had broken loose from the main body and migrated down into some irrelevant place in the code. Who hasn't seen a comment that, like junk DNA, had been copy/pasted over and over again into various places in the code and then left to rot.

Even our IDEs nowadays recognize how little value comments have -- they pain the comments in italic grey so that we know to ignore them.

When you write a module that is messy or complex, do not think: "Oooh, I'd better comment that." Rather think: "Oooh, I'd better _clean_ that!".

This isn't to say that you should never write comments. Of course you should. You should write comments whenever you fail to find a way to get the code to describe itself. And you should consider it a failure! I do not congratulate myself when I find I must write a comment. I chide myself for being unable to find a way to get the code to express itself.

What about javadocs? I think they are great for public APIs. I don't think they are very useful for code that is written and used by a team. I especially hate Javadocs that add nothing to the function. Have you ever seen a Javadoc that can be completely removed from the code without changing what the Javadoc engine will generate?

Finally, and most importantly, the worst kind of comment is commented out code. This is an abomination that must be deleted at every turn. If you see commented out code, DELETE IT without hesitation. Expunge it from existence. Utterly obliterate it! I guarantee you that you won't lose that code, because it's still there in the source code control system (you _are_ using one, aren't you?) I also guarantee you that you'll never go looking for it either.
 
Ilja Preuss
author
Sheriff
Posts: 14112
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Originally posted by Robert Martin:

they pain the comments in italic grey so that we know to ignore them.


Nice typo.
 
Jeff Langr
author
Ranch Hand
Posts: 799
5
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Originally posted by Robert Martin:
Even our IDEs nowadays recognize how little value comments have -- they pain the comments in italic grey so that we know to ignore them.


I've turned them white a few times. Produces an odd but soothing effect in code where comments were overwhelming.

Jeff
 
Ilja Preuss
author
Sheriff
Posts: 14112
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Originally posted by Jeff Langr:

I've turned them white a few times. Produces an odd but soothing effect in code where comments were overwhelming.


Interesting idea...
 
Vijay Venkat
Ranch Hand
Posts: 52
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator

Most comments are lies. They don't start out to be lies, but gradually the get out of date.

This is what i have seen happen the most. Since code is mostly changing, the comments goes out of context very soon.
While in certain places, like there is a bug in some other product that needs to be worked around, i try and a comment with in the function and point to the bugs as a link, also with a TODO to keep a tab, so that it can be removed once the bug is fixed. But the function name will surely reflect the problem that is being worked around.

When the bug is fixed, the function along with the code is removed.

Thanks,
Vijay Venkataraman
 
arulk pillai
Author
Ranch Hand
Posts: 3387
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
When the bug is fixed, the function along with the code is removed.



Isn't this hard to police?
 
Vijay Venkat
Ranch Hand
Posts: 52
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi arulk pillai,
That's a very good question.
That's where some discipline comes in to play.

When we talk about clean code - it's learning and discipline put in place.

For every good product that is there, there is one or many people who follow good development discipline. I am sure they keep a tab on this.

There are plugins which show all the todos that is in the code and contant vigil is kept on the todos. Else todos list will grow beyond a point.

There are occasions i had filed bug on another product, but had to work around till it was fixed in that product. Once it is fixed, we got the work around removed.

For these cases? then i would ask, what is the best way to handle?

Thanks,
Vijay Venkataraman
 
Alaa Nassef
Ranch Hand
Posts: 471
Hibernate Mac OS X Spring
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Originally posted by arulk pillai:
Isn't this hard to police?


Not really, since the TODO comment will say that it should be removed after bug number XYZ is fixed. Of course it might be quiet hard if you have something like ten thousand TODOs
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic