5 reasons to avoid code comments

comment


DISCLAIMER: When I say ‘to avoid code comments’, it doesn’t mean that I don’t write comments, it means that I try to avoid code comments as much as I can, but sometimes I do, when I think it worth.

We spend more time reading software than writing software. I never seen any scientific study proving it, but in software field it’s like a dogma or a common belief. Due to it, it’s important to try to write software easy to read, it’s important to care about the readability of our code. There are some techniques that programmers can use to achieve it. One of them, is write code comments.

When talking about code comments, there is big debate about it. Should we use comments to describe what our code does ? We should focus on write expressive code that doesn’t require comments to be read ? Joe Kunk wrote a blog post about this debate – To Comment or Not to Comment. There are the ones who say that for a code be considered good it should be well-documented and there are the ones who say that we should avoid comments because it’s normally used to explain/hide bad code.

In my opinion, influenced by the books, Clean Code and Refactoring, we should avoid to write comments unless we have a really good reason to write one (for example,in a mathematical algorithm) or we are obligated to do it due to some company rules or process. Below, I listed my 5 concerns about code comments.

Where I think that code comments fail

1. They tend to encourage bad code. There is an idea that commented code is a good code, so people often write comments in their code to make them look better. If we need to explain our code adding comments is already a signal that maybe we are writing bad code. Every time we start to write a comment we should think if we can be more expressive just cleaning our code.

2. We spend more time writing and maintaining them. Comments usually are a second version of the code. When we are writing a comment for a function we are repeating ourselves. We are transgressing the DRY (Don’t Repeat Yourself) principle. We are spending time and adding complexity. Software requirements changes and code has to change too. If we are writing comments we have to maintain the comments too. So we can end up spending the double of the time when we have to make a change. We could use this time to improve our code or to develop new features.

3. Comments are not testable/verifiable. When we are changing code we can rely on tools, like compilers, IDEs and unit tests to help us. Comments don’t. Comments don’t have these tools. You can’t rely on tools or unit tests to make sure they are right, in the correct place or out-of-date. Once you write a comment you have a not testable piece to care about his correctness and once it fails, it will fail silently.

4. They are less reliable than the documented code. Usually, comments become obsolete and they lose the connection with the code. Then, programmers can read them, and be cheated. Even if the comments are up-to-date, the only way to know if the code does what it should, will always be reading the code. A practical example, if our boss ask to us if a change was made, where we should look ? Code or Comments ?
Of course we will look at the code.

5. Some comment styles can fill a lot of screen space. Some comment standards (like the below) use a lot of lines being a problem when you are trying to read as much code you can.

/**
* 
* @param title The title of the CD
* @param author The author of the CD
* @param tracks The number of tracks on the CD
* @param durationInMinutes The duration of the CD in minutes
*/
public void addCD(String title, String author, 
int tracks, int durationInMinutes) {
CD cd = new CD();
cd.title = title;
cd.author = author;
cd.tracks = tracks;
cd.duration = duration;
cdList.add(cd);
}

22 Comments

  1. Comment by David J.:

    Your example #5 does not meet the criteria of a “code comment” rather it is an API comment (public method) which should define a contract and can be exported and consulted without having to access to the source code.

    High-level design needs to be commented on as well – somewhere – but low-level implementation details should be self-explanatory from the code. API comments are useful in the middle to make the system easier to learn to use when trying to discover what can be done as opposed to how it is done.

  2. Comment by Timur M.:

    Code describes how a problem is to be solved. Comments should be used to describe /why/ a problem is being solved in a particular way. And not in one of thousand other ways. This information is not contained in code. The machine doesn’t understand what it does and doesn’t need and wouldn’t understand this information anyway. But humans need to.

    Comments do not encourage bad code. This is simply not true. At least not in the general sense. But obviously not all comments are helpful. Writing good, coherent comments is an art. Just like writing good code.

    • Comment by paulo ortins:

      Timur, when I said “avoid comments”, it doesn’t mean ‘I don’t use comments’. There are good comments. There are places where we can use english, that is a more expressive language than any programming language, to explain ideas about our code. But when I mean ‘encourage bad code’ is because people usually use comments to explain bad code, to justify a code that could be better written.

  3. Comment by George:

    The problem isn’t so much that we read code more often than we write it – that’s certainly true – it’s that the reason we are usually reading it is that we are debugging. We find ourselves tunnelling into a mass of foreigh code wondering if this is the location of the bug or not.

    Of course we can work out what the code’s doing. The question is: is this what was intended? And right now, my mind is a cache of information about the bug I’m chasing. I don’t want to flush it by having to figure out what this function I’m just about to step through is trying to do.

    While reason 1 is nonsense, reasons 2..4 are all good but they should be flagging up the real issue to you: why is support for documentation of code so poor? Why are we still writing code as ascii text files? IDEs could provide so much support to address issues 2-4 but they still think it’s the 1960s.

    • Comment by paulo ortins:

      “I don’t want to flush it by having to figure out what this function I’m just about to step through is trying to do.”

      Good names, short functions, in other words, clean code, should resolve it.

  4. Comment by Christian Walde:

    You fall afoul of a simple maxim in soap-boxing:

    Do not tell people not to do. Tell whem what to do and why.

    In this case, you forgot to mention the two important dos:

    1. If you write a comment, have it explain WHY a piece of code is like it is, not what it does.

    2. If you are tempted to write a comment to summarize what a block of code does; you want to refactor that into a new subroutine.

  5. Comment by Volodymyr:

    6. Undocumented code is great for job security — nobody will understand your code, so risk to be fired is reduced a lot.

    7. Undocumented code is great weapon against boring peer-review. Who will bother to do peer review which will take hours to complete?

  6. Comment by Loïc Prieto:

    Hi there,

    thanks for the insight.

    I also have to comment the example #5: It is a good example of a comment that serves no purpose whatsoever. It doesn’t really explain what the addCD function does on a high level. add a CD to where? how?

    I find that params themselves do not need explaining if they are well named. flag params, however do deserve detailed explaining (and i’m not a big fan of flag params, i would prefer another function, for clarity).

    I’ve inherited recently a suite of programs that need maintenance, and no documentation whatsoever, and what i really hate the most is that the code is not commented at all, leaving me to discover what a function really does by the lengthy and tortous process of tracing the code from top to bottom. Needless to say, i still have SLAs to respect. A hellish project, in truth. Comments would save me a lot of time, though i do admit the main problem comes not from the lack of comments in the code, but rather from the lack of high level documentation. But stil…comments would have done wonders.

    • Comment by paulo ortins:

      This is how I think:

      The programmer’s priority is write good code, when we didn’t achieve it we tend to use comments to justify our failures. Of course, sometimes comments are the best tool to use, but I think that it should be rare.

  7. Comment by Mariusz:

    This is a comment

  8. Comment by Väinö Leppänen:

    All in all the arguments are pretty weak. I’ll agree with the goal though: try to have as little comments as possible but only by using other means to clarify the intent of the code. First, the tendency of any given practise is almost irrelevant. Goto has the tendency to result in spaghetti code but there are situations where the code would be really nasty without using a goto. You look at a piece of code and you try to make the intent as clear as possible. Since we don’t infinite amount of time to polish the code, add comments to finish it off if it’s necessary.
    The second point describes exactly how comments are not supposed to be used because it’s pretty stupid. You use comments to summarize and clarify intent (and probably for other valid reasons). They are there to help the reader. I’ve seen some pieces of code that were relatively short (5 – 10LOC) and filled with bit shifting and masking. I would’ve paid real money for a good comment that says what the hell those binary operations are supposed to be doing: the intent of codes lines.
    The third point is actually valid. When something can be validated or checked, use unit tests or some technique like asserts.

    • Comment by paulo ortins:

      1. I think we should care about a practice tendency. Goto has a tendency to used to write bad code and this was one of the the reasons to we aren’t using goto anymore. My point is, we usually are writing comments where we should be cleaning the code.

      2. If these pieces of code (5-10 LOC), were splitted in smaller functions (2, 3 LOC) with significative names, do you think you would need comments ? If yes, ok, here is a good reason to place a comment, but this type of comment shouldn’t be a rule.

  9. Comment by Julio:

    I recently blogged about this same topic here: http://julipedia.meroh.net/2013/06/readability-avoid-comments.html . However, I did so by providing 4 specific examples in which comments are useless and rewriting the code to make it more readable is preferred.

  10. Comment by itoctopus:

    I have to agree with this post – many times when reading a comment I get confused. Is this comment up to date? Is this comment still valid?

    The problem is that most of the times, the comment is scary (such as “DO NOT REMOVE”) and one has to read a lot of code just to verify whether that comment is right or not.

    I’m with commenting the functionality of the function, but not with commenting a change somewhere that may or may not temporary.

  11. Ping from 避免代码注释的五大理由 | 小样儿(ShowYounger):

    [...] 代码注释的作用一直以来都被程序员们广泛讨论。很多人认为注释不是必要的,写注释那是因为代码可读性太差了。原文作者Paulo Ortins发表了博文《5 reasons to avoid code comments》,以下为译文: [...]

  12. Ping from 避免代码注释的五大理由 _ 移动互联网 _ HTML5工作室:

    [...]        代码注释的作用一直以来都被程序员们广泛讨论。很多人认为注释不是必要的,写注释那是因为代码可读性太差了。原文作者Paulo Ortins发表了博文《5 reasons to avoid code comments》,以下为译文: [...]

  13. Comment by Volker Schneider:

    Great post. Junior developers and students all over the world are told that the lack of comments is bad and makes code unmaintainable. But are never taught HOW to comment. So they figure, “the more inline comments I have, the better my code quality” (I have seen this being taken to an insane level).
    This mindset is backed by a very subtle effect: the knowledge that commenting is hard creates the feeling of it being a necessary evil that all pros have to do. But this is often only true if you are writing bad code in the first place, like you pointed out in #1.
    As of #5 on your list, there should definitely be better IDE support to manage that kind of mess!

  14. Ping from 百度运营产品研发团队:

    [...] 代码注释的作用一直以来都被程序员们广泛讨论。很多人认为注释不是必要的,写注释那是因为代码可读性太差了。原文作者Paulo Ortins发表了博文《5 reasons to avoid code comments》,以下为译文:  [...]

  15. Ping from 誒!到底要不要寫註解啊? | The Road:

    […] 我想這篇文章說明了一些關於註解的兩三事,5 reasons to avoid code comments 。 […]

Leave a Reply

Your email address will not be published. Required fields are marked *