my comments about redundant comments

cover image by MartinHarry , licensed under Public Domain

It is generally a good idea to think about why you are doing things the way you currently doing them.

Sometimes you are faced with a new situation, and don't quite know what the correct or best way to handle it is. Hopefully you don't just do whatever happens to first pop into your mind. You take some time to think about it, and consider the pros and cons of each alternative.

In this post I'm going to talk about my opinion on doxygen (or javadoc) comments.

I remember learning about doxygen and how amazed I was at the idea of a tool that could extract documentation from the code itself. I started using it in the code I wrote, but sometimes others on the team were not so keen on documenting what they did. Being "forced" the corporate rule to document every single piece of code didn't feel so bad at the time. At least everybody would have to document their code. And then I started diligently following that rule and documenting every little bit of code I wrote.

All was good. But admittedly a bit boring at times.

A few years passed, and I kept (trying) to follow that rule, but things didn't always work out. Sometimes I would not have enough time to document everything, and would just document the essential parts, but would feel bad for not reaching the level of quality I had set myself up to.

I then read Clean Code, and it caused me to rethink many of my assumptions. Time to put into practise the last paragraph of the Agile Manifesto:

At regular intervals, the team reflects on how
to become more effective, then tunes and adjusts
its behavior accordingly.

Consider what you are actually contributing to the project when you write this documentation:

  * @brief Default constructor.

Yes. I can see its a default constructor. Or this one:

  * @brief Gets the converted mana cost of the card.
  * @return The mana cost of the card.
ManaCost getConvertedManaCost() const

Yes, yes. Two lines in the documentation restating what anyone can clearly see in the method signature.

It would be far more useful to invest time in the description of what those two classes (Card and ManaCost) represent, than to add redundant information.

If you are not diligent enough to keep these useless comments up to date with any code refactors you do, you will end up with a far worse kind of documentation. The outdated and potentially misleading kind.

And after all this I had convinced myself.
From now on I will:

  • Not waste time or effort on redundant doxygen comments.
  • Only write them if they add extra information that you cannot get by just reading the public facing code (e.g. the method signatures).
  • Often remove these redundant comments from code I happen to refactor.


Rui Pires

Working as a professional full time remote developer from the Azores since 2011.

Read More