Don’t comment bad code—rewrite it

Ashkrit SharmaNovember 13th, 2019Last Updated: November 4th, 2019

1 275 2 minutes read

In this post i will share my experience of “comments in code” that i have got by reading code , writing code and reading books.

Lets start with famous quote

“Don’t comment bad code—rewrite it.”
  —Brian W. Kernighan and P. J. Plaugher

Lots of comment in code looks just like above image and it is distraction.

Comments are lie
Most of the time comments are not in sync with code, no one cares about it so no one maintains it.

Code is refactored
Code is under constant improvement, it changes , evolves and dies but code comments just sticks and become orphan.

Bad code has more comments
Once we write code that is hard to understand then we try to explain it by comments and it tells lot about our failure to write expressive code.

Noisy comment
Lets look at at some code+comment from public domain.

https://github.com/apache/hadoop/blob/trunk/hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/client/HdfsAdmin.java

/**
   * Create a new HdfsAdmin client.
   *
   * @param uri the unique URI of the HDFS file system to administer
   * @param conf configuration
   * @throws IOException in the event the file system could not be created
   */
public HdfsAdmin(URI uri, Configuration conf) throws IOException {
FileSystem fs = FileSystem.get(uri, conf);
if (!(fs instanceof DistributedFileSystem)) {
throw new IllegalArgumentException("'" + uri + "' is not an HDFS URI.");
} else {
dfs = (DistributedFileSystem)fs;
}
}

This code snippet is from popular open source java project, many comment in enterprise is also like this. This adds more noise than value.

Journal comments
Many scripting code, data base code, python code is based on this pattern, this looks like team has no trust on source control and they have taken over this responsibility. It looks something like below

/*
01-Apr-2019 – First version with skeleton code by someone
10-Apr-2019 – Config support added by someone
….
…
*/

Marker comments
This starts with something like below

// Starting init

//Make DB call

this is also very common in scripting, DB stored procedure or in real enterprise type programs. This patterns tell that it is shouting to extract small function but gets overlooked.

Commented code
I am sure you have seen this many time and got frustrated that why this dead code exists.

It looks something like this.

//Keeping this for backup
//fastCode()

superFastCode()

Author code
IDE adds block of comments to every file that is added to project, it looks like below

/*
@Ashkrit
*/

Author names is just at the top of the file but he no more maintains it and does not work for team or organization but occasionally gets credit/blame for his creation.

Conclusion

Code Comment mostly adds no value, it comes between you and code, it is one extra distraction.It also promotes bad habit for young programmer because they think ” adding comments makes code better“.

In some case comments are useful when you are writing public APIs but still be careful on what you write, software engineers are smart they can understand if code does not have accidental complexity.

I will leave you with another famous tweet by Kevlin Henney

If you like the post then you can follow me on twitter.

Published on Java Code Geeks with permission by Ashkrit Sharma, partner at our JCG program. See the original article here: Don’t comment bad code—rewrite it

Opinions expressed by Java Code Geeks contributors are their own.