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}

Code comments gone wrong from our
JCG partner Christophe Roussy at the
Javarizon blog.

Source :

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