markdown guide
 

I was totally against writing documentation when I was younger but now I document every function in header file and every static one in source file. What I don't do is pollute function implementation with unnecessary comments. A few comments here and there are fine if something is ambiguous enough to require some explaining. I am doing it for myself because without it, when I stay away from the code even for a week, I am already confused and having hard time following my own insidious creations 😁.

 

There are at least 3 factions in the software industry around code documentation:

  1. Developers who refuse to write code comments.
  2. Developers who always write code comments, as they see it as an intrinsic and critical aspect of writing code.
  3. Developers who are ambivalent and/or add comments where they feel it is needed.

I am in the first camp: I never write code comments unless they fall into 3 distinct categories:

  1. TODO - An indication that a piece of code is intentionally not in its final form, as would happen in an iterative development process.
  2. FIXME - For a bug that needs to be fixed, but for whatever reason cannot be fixed immediately
  3. REFACTOR - A comment explaining what needs to be done to improve an area of code.

My reason for not writing comments that reflect the code they comment is best explained by Bob Martin in Clean Code.

Classic DEV Post from May 24

ECMAScript Classes - Keeping Things Private

Ravi Dhiman profile image

DEV is sort of like Medium, but it's open source and 100% focused on developers.

Now reaching over 3 million visitors per month, it's the fastest growing software development community in the world.

It's free, devoted to the open web, and will never have popups or a pay wall.

Get Started Now