Have you ever seen a stop sign with another sign below it that says, “This is a stop sign”?
…
No, me neither.
Yet, step into any codebase and you’ll trip over comments doing exactly that:
The Department of Redundancy Department strikes again!
Now, maybe you’re thinking, “Hey, it’s just some harmless noise.” Sure, but don’t get too comfortable, because i have a whole bunch more!
1. Lies, damned lies and Comments
Comments sometimes are like politicians: they promise one thing and deliver another. Maybe someone updated the function but forgot about the comment , or they just copy-pasted without updating it.
No matter what is the cause: The comments might lie, the code will not.
2. TODO or NOT TODO, that is the question
Do you know the situation where you leave something in the back of the fridge and months later it’s still there, completely spoiled, and you pretend not to see it? // TODO: Refactor this. is the digital equivalent of exactly that.
Adding those TODOs while developing is fine; But merging a pull request littered with TODOs? Nah. Do your team a favor: turn TODOs into real tasks in your project management tool and actually assign them. But beware because in task management land a place called “Backlog” exists, which is a synonym for “Graveyard”.
Speaking of graveyards…
3. Comments Are Not a Code Graveyard
Commented-out code just clutters the codebase. If you’re not using code anymore, delete it. You can always find old versions in the git history if you need them. In nine years as a developer, I’ve rarely had to recover old code from comments.
So then what does a useful comment look like?
Practical Tips for Writing Good Comments
1. Do not write the comment in the first place
Whenever you think you will need a comment to explain what is happening, pause. Can you clarify the code? Comments become unnecessary when the code itself tells the story.
2. Explain the Why, Not the What
The computer cares about what the code does. Your fellow developers care about why you made it do that weird thing. If you had to pick a workaround for a browser bug, or hack something to work around an API quirk, write that down.
Do not do this:
// Wrapper div is neededDo this instead:
// Wrapper div is required for Firefox, see: https://bugzilla...3. Reference Issues and Tickets directly
Link to relevant issues, Jira tickets, or merge requests right in your comment. This gives context and traceability.
// Some users don't have an id... Why? See issue: #756
if (!user.id) { ... }That way, when someone’s looking through the code six months later, they will not end up deleting something that is actually needed or asking you why its there.
4. KEEP IT SIMPLE, STUPID
Nobody is going to read a novel in a code comment. If you need more than a couple of lines, consider if the information should go elsewhere, such as developer documentation or a linked issue.
Write simple code that speaks for itself, comment only to explain the why and don’t litter the code with TODOs nobody will tackle.
Cheers! ✌️