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}



9 thoughts on “Code comments gone wrong

    • The point is that sometimes it is better to have some extra code. This extra code will make the code more readable by breaking down the action into smaller steps. So yes you can have an extra method.
      Personally I would change it into a method only if the concerned piece of code also appears in other parts of the program (to remove duplication).

      • A good reason to decompose a process into steps defined in separate methods, even if they are only called once, is so that those individual methods are testable.

  1. Pingback: Code comments gone wrong | Eclipse | Syngu

  2. Pingback: Code comments gone wrong | All of Java

  3. I totally agree. Also next to using assertions I’d also 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.

    • 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.
      Now I use both assertions and those annotations, I also post some questions and answer questions on that topic on StackOverflow.
      Your blog looks interesting, hope to see some of your articles on dzone or java code geeks.

  4. I blog frequently and I genuinely thank you for ypur content.

    Thiss article has truly peaked my interest. I’m going to
    take a noye off your blog and keep checking for new information about once a week.
    I opted in for your RSS feed too.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s