Code Comments are Lies

Code Comments are Lies

2015-02-02clean codecomments

Post Update

This post generated some interesting comments on the code project site. Here are some things to note before you continue.

  • This post is aimed at higher level languages like C# and Java. Please comment your FORTRAN etc.
  • The best code that you can write is code that is maintainable as this is the true cost of software. If this requires you to add a comment please do that. I also do that.
  • A comment as an excuse for writing bad code, is unacceptable.

Please read the comments on code project. There are some valuable usecases there.

I'm going to make a bold statement.

YOUR COMMENTS ARE BAD AND YOU SHOULD FEEL BAD

We got a Bad Ass here

"Oh no he didn't". "My comments are informative and well written." "How else would people understand this awesome piece of efficient code?"

Although there are use cases for comments, I am going to tell you that comments are like little poops that you leave all over your code for you fellow devs to step in.

Let's look at some truths about comments

  • They can state the obvious, thus being redundant. 

     // The Persons First Name
 public string FirstName { get; set;}

  • Having comments scattered throughout your code, explaining functionality in detail, makes it hard to read code fluently. This means that extra effort and concentration is needed to read between the comment lines. The intent does not jump out at you.

Comments Become Lies

  • Comments rarely get updated when the code changes. This means that overtime the functionality documented by the comments, drifts away from what is actually happening. This causes confusion and again makes the comments worthless.

  • ToDo Comments. They usually don't get done.

  • Comments get copied with code, and as the code changes again the comments don't. First of all you should think twice when you need to copy code, and if you have a great reason you have to make real sure to update (or even just remove) the comments made.

  • Finally, like Uncle Bob says in his book Clean Code, if you need to write a comment you have failed to express the intent of the code. You want your code to read well, to be self-documenting so that you do not need to document it.

I have written all these types of comments.

I need to write a comment about my code, thus I have failed

This is another bold statement. But it is exactly what I tell myself when I need to write a comment. It forces me to rethink my code and usually rewrite it to be more readable and maintainable. And if I still need to write the comment, it reminds me that I still have room for improvement. I can decide to leave out the comment and not feel bad, but I write it in hopes that it might aid me or whoever comes after me to understand my poorly expressed code.

So What Can I Do To Fix This Problem?

First of all, Name Things Well. Well named classes and functions and properties help eliminate confusion and clarifies code intent. A function should do what it says, a class be what it is named.

Functions should do one thing, it should do it well and it should do it only. Following the Single Responsibility Principle will eliminate most reasons to comment code.

But I hear you shouting from afar: "Pieter, not all comments can be bad". This is true, although I still maintain comments are bad.

Some Good Comments

  • Comments that you write to document badly written legacy code. It is not always possible to refactor code, so in these cases help yourself and others to document things that might have bad side effects.

  • Comments documenting framework limitations. 

    public FooConstructor() { //EntityFramework requires a default constructor }

  • ToDo comments can be a great way to remind yourself of something that you need to do. Only use them while working on feature branches. They should be implemented or removed (placed on your backlog as a ticket) once you merge back to your main branch.

  • In the rare case that you need to write optimised code that might be confusing and not easily readable. This is a rare case for most of us.

  • API documenting code. In some languages you can add comments to classes, methods and properties and these will get rendered by your IDE or can be exported to actual documents. This should only live on public facing code and has no place inside your application where some random user will not use it.

Remember you want to write readable, self-documenting, maintainable code for yourself and others. So stop writing that comment and be awesome instead.

If you can think of other examples please add them in the comments and if you liked this post share it with the hashtag #badcomment. For those of you that are still angry, here are some funny comments.