Dear Future Me: Please Add Comments While You’re Coding.

4 years ago I started a project called Brackets Ninja which is a tool for managing tournament and creating brackets online.

One of the main challenges I had while I developed this project was to create an algorithm that given a number of participants — knows to create a tree for drawing a single elimination bracket (?) with HTML. I know, it doesn’t sounds like the hardest task you’ve ever heard of, but back at this time I found it quite challenging.

As you may guess, the code I wrote back then isn’t exactly the Mona Lisa, and I didn’t document it at all. A few hundred lines of code, and not a single piece of comment.

Oh wait, there was actually one comment I left:

Thank you for that…

It’s not that I have something against adding comments to the code I’m writing, it’s just that I didn’t think someone will ever touch it. Including me.

Well. I was wrong.

My costumers asked me to support double elimination brackets (?) — which led me to face my worse nightmare: understanding an algorithm young me wrote a long time ago and adding more features to it.

Facing code I wrote 4 years ago is like…

TL:DR; I needed to rewrite the whole function (it turned out I was a horrible developer!) - this time with a book of comments.

Lesson learned, and here’s why I think you all should be strict on adding (without generating the automated code annotations) comments on the code you’re writing:

• Because you may never know who’s going to access the code you’re writing and when. While you sure that the code you’re writing right now is the most beautiful, clear, and smart code the humanity ever witnessed — it won’t be the case in the (near) future.
• Your code should be accessible for developers on all kind of levels, including junior developers.
• Even if you’re being careful with naming classes, functions and variables, it’s not necessarily the conventions other developers are being used to.
• Good code is not self-documenting. Really. It doesn’t. You should add comments that clarifies the meaning and purpose behind the code you wrote so it would be easier to understand it.

Just to be clear — I’m against obvious, boring, linted, or unit tested comments. The type of comments I’m referring to is the one that explains a non-trivial code. For example, comments about browsers compatibility workarounds, a reference to specific section in a library’s documentation, a reason why I chose one approach over another one, etc.

WDYT? Let me know 😎