All Articles

Comments should be about the why

At the start of my career I was really triggered by code comments. Reading Clean Code over and over made comments stand out like a wort in every file.

I’m not gonna talk about comments which should not exist, but only share a point learned through tough lessons in my career.

Comments should explain the why, I can figure out the what from the code (hopefully at a first glance), but in some cases you will never be able to figure out the why just from the code. In the same note as commits, comments should be about the why and not about the what. This are the comments that I would’ve loved to be there.

PS: do not add just the ticket number as a comment, as most likely in 10 years that JIRA board will no longer be there

Published Dec 1, 2020

Software engineer.