aspose file tools*
The moose likes Agile and Other Processes and the fly likes Clean Code: A Handbook of Agile Software Craftsmanship - comments in code Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login
JavaRanch » Java Forums » Engineering » Agile and Other Processes
Bookmark "Clean Code: A Handbook of Agile Software Craftsmanship - comments in code" Watch "Clean Code: A Handbook of Agile Software Craftsmanship - comments in code" New topic
Author

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

seema prakash
Ranch Hand

Joined: Nov 17, 2004
Posts: 59
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

Joined: Jul 11, 2001
Posts: 14112
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.)


The soul is dyed the color of its thoughts. Think only on those things that are in line with your principles and can bear the light of day. The content of your character is your choice. Day by day, what you do is who you become. Your integrity is your destiny - it is the light that guides your way. - Heraclitus
seema prakash
Ranch Hand

Joined: Nov 17, 2004
Posts: 59
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

Joined: Sep 30, 2004
Posts: 106
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.


Thanks,<br /> <br />Paul Croarkin<br />SCEA 5, SCWCD, SCJP
Jeanne Boyarsky
internet detective
Marshal

Joined: May 26, 2003
Posts: 29255
    
140

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.


[Blog] [JavaRanch FAQ] [How To Ask Questions The Smart Way] [Book Promos]
Blogging on Certs: SCEA Part 1, Part 2 & 3, Core Spring 3, OCAJP, OCPJP beta, TOGAF part 1 and part 2
Katrina Owen
Sheriff

Joined: Nov 03, 2006
Posts: 1344
    
  12
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

Joined: Jul 11, 2001
Posts: 14112
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

Joined: Jan 28, 2008
Posts: 460
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.


Visit my blog: http://jnassef.blogspot.com/
Jeanne Boyarsky
internet detective
Marshal

Joined: May 26, 2003
Posts: 29255
    
140

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

Joined: Jul 11, 2001
Posts: 14112
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

Joined: May 14, 2003
Posts: 762
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


Books: Agile Java, Modern C++ Programming with TDD, Essential Java Style, Agile in a Flash. Contributor, Clean Code.
Robert Martin
Author
Ranch Hand

Joined: Jul 02, 2003
Posts: 76
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.


---<br />Uncle Bob.
Ilja Preuss
author
Sheriff

Joined: Jul 11, 2001
Posts: 14112
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

Joined: May 14, 2003
Posts: 762
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

Joined: Jul 11, 2001
Posts: 14112
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

Joined: Aug 12, 2001
Posts: 52

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

Joined: May 31, 2007
Posts: 3216
When the bug is fixed, the function along with the code is removed.



Isn't this hard to police?


Java Interview Questions and Answers Blog | Amazon.com profile | Java Interview Books
Vijay Venkat
Ranch Hand

Joined: Aug 12, 2001
Posts: 52
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

Joined: Jan 28, 2008
Posts: 460
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
 
I agree. Here's the link: http://aspose.com/file-tools
 
subject: Clean Code: A Handbook of Agile Software Craftsmanship - comments in code
 
Similar Threads
java documentation
JTextPane coloing singular words.
late code comments - risk ???
Too Many Comments?
Use Join Fetch but still obtain LAZY exception