Code comments gone wrong

Adding code comments is supposed to be good practice, but here is why it often fails:
  • Code is the single authoritative source of truth in a program!
  • There is no way to ensure that code comments are correct at all times (not always updated as code changes).
  • Comments are written in human language which can be prone to misinterpretation.
First put your good intentions into writing simple and readable code.
Write self descriptive code ! Your code should be read like sentences. Avoid smart shortcuts and tricks because they break the reading. Expect the reader to have solid programming knowledge but no knowledge about the purpose of your code. If code is too compact add extra code steps to document it, for example:
...
final Person dummyPerson = new Person("Joe", "Bloggs");
return dummyPerson;
Instead of using a comment:
...
// Return dummy person.
return new Person("Joe", "Blogs");
Ok ok, this example was a bit silly but you got the idea.
Using long names is considered bad practice, I disagree. Prefer using long explicit names over short meaningless names which require code comments. Sometimes long names are really annoying, for example when they keep appearing everywhere in some algorithm, in that case you could use a comment.
Consider using more columns:
The default max of 80 columns is terrible, use a wide screen and use 120 columns or more, the code will be more readable because long lines will not wrap anymore and you can use longer more explicit names.
Use assertions to document pre and post conditions instead of lengthy comments.
public List<String> listFiles(final String folderUrl) {
assert folderUrl!= null;
assert folderUrl.endsWith("/");
  ...
}
If you write an API a good documentation is necessary but for internal code I think comments should not replace good naming and code clarity. I use code comments when the code is not really self documenting. Comments should convey what code cannot. They should explain the reasons for a specific design decision, they should explain what code is supposed to achieve and why.
Learn how to use the Javadoc, it not only looks better, it can also help automatically update some documentation. When referring to code try using the link tag. Your IDE may automatically update the linked method and class names during renaming which ensures that some of your documentation stays up to date.
/**
* Use the link tag: {@link SomeClass#someMethod}
*/
Links:
Reference: Code comments gone wrong from our JCG partner Christophe Roussy at the Javarizon blog.
Related Whitepaper:

Software Architecture

This guide will introduce you to the world of Software Architecture!

This 162 page guide will cover topics within the field of software architecture including: software architecture as a solution balancing the concerns of different stakeholders, quality assurance, methods to describe and evaluate architectures, the influence of architecture on reuse, and the life cycle of a system and its architecture. This guide concludes with a comparison between the professions of software architect and software engineer.

Get it Now!  

3 Responses to "Code comments gone wrong"

  1. I totally agree. However, instead of using assertions I’d rather use JSR 305 Annotations like @Nonnull, @Nonnegative, @Nullable etc. Those can be placed on parameters and return values and help to further describe an API. Also it is not only visible to the programmer but also to the IDE so good ones like IntelliJ can perform static analysis and provide actual warnings or errors based on the given constraints.

    Actually, it’s not “instead” – use both: Annotations where possible and assertions to check complex constraints.

  2. Christophe says:

    Hello Andreas,
    I now heavily use those annotations along with FindBugs but at the time I wrote the article (2011) I did not know about them.
    It would be nice if you could comment on the original article on my blog.
    Now I use both assertions and those annotations.

  3. Oops,

    JavaCodeGeeks sold it as new content on google+ therefore I didn’t check the date ;-)

Leave a Reply


8 − = two



Java Code Geeks and all content copyright © 2010-2014, Exelixis Media Ltd | Terms of Use | Privacy Policy
All trademarks and registered trademarks appearing on Java Code Geeks are the property of their respective owners.
Java is a trademark or registered trademark of Oracle Corporation in the United States and other countries.
Java Code Geeks is not connected to Oracle Corporation and is not sponsored by Oracle Corporation.
Do you want to know how to develop your skillset and become a ...
Java Rockstar?

Subscribe to our newsletter to start Rocking right now!

To get you started we give you two of our best selling eBooks for FREE!

Get ready to Rock!
You can download the complementary eBooks using the links below:
Close