The best comments are the ones we don't write

I've read several articles on “good comments”, I've written some, I've read technical books about “good comments” and I work on a JavaScript project where everything must be commented (jsdoc). I changed my mind about that matter.

⚠️ Read more of my blog posts about tech and business on my personal blog! ⚠️

Self documenting code

What I've learned from my experiences and my reading can be summed up by the title of this post.

The best comments are the ones we don't write.

When you feel the need to write a comment, it's usually because your code isn't as clear and clean as it should be.

Compare this :

function main() {
  let imageName = 'test.png'

  // Get the extension off the image filename  
  let pieces = imageName.split('.')
  let extension = pieces.pop()
}

The comment in itself isn't a bad thing. The developer may judge that we could need them later to understand the code better. He puts a comment, it's nice.

But it kind of looks like an excuse : "My code is ugly/complicated but it's not that bad, I'll explain it in a comment" instead of cleaning it.

function main() {
  let imageName = 'test.png'
  let extension = getFileExtension(imageName)
}

The name of a function is already supposed to answer the question of what a code part does. Why not use this possibility?

Too much comments suffocates the code

As indicated above, on my current project we have to document everything. Everything must be commented with jsdoc.

There's nothing bad about it. But in the end, most written comments are comments used solely to pass tests. They're redundant and useless.

/**
 * Get the extension of the file
 * 
 * @param {string} filename - The filename
 * @return {string} the extension of the file  
 */
function getFileExtension(filename) {
  let pieces = imageName.split('.')
  return pieces.pop()
}

Tell me there's an info in that comment you didn't get while reading the code?There's none.

On the contrary, the fact that the function returns the extension of a file is repeated thrice : once in the name of the function, once in the function's description and once in the @return tag.

What is the added value of this comment? There's none.

When you keep seeing useless comments, your brain learns to ignore them. You've probably experienced this before : on a project where there are many comments and a majority of comments like the one we've seen above, you end up not seeing or reading the comments anymore.

Unfortunately, the few interesting comments get lost in the sea of useless ones and aren't as useful as they should.

Code coverage by documentation

As for unit tests, there are a bunch of tools that exist now to measure the code coverage for comments by documentation.

And as for unit tests, you're quickly tempted to reach the 100% coverage.

And as for unit tests, I'm not sure this is something worth doing. For unit tests, a high coverage isn't reliable and isn't a proof of quality ; for documentations, a high percentage of coverage isn't counter-productive and suffocates the code.

By forcing developers to write documentation everywhere, we force them to write lame documentation.

Where the code is clean, the comment will be useless, and your brain will soon ignore it. Where the code is messy, the developer will use the comment as an excuse to not upgrade its code.

I write less comments

… and it's not a bad thing. The code is easier to read. It forces me to make my code as self-explanatory as possible : thus, the code is cleaner. Readers will pay more attention to the few comments I write.

The only problem I'm facing today is in the context of a project with an auto-generated public documentation. How to avoid redundancy while making sure the documentation generated from my comment is complete.

To dig deeper, here's a more recent post that goes deeper into explaining the concept/idea presented here. It follows the feedback and questions from readers :

• La documentation sera toujours utile