Clean Code
The Art of Writing Comments that Explain Nothing
January 25, 20244 min read
The Classic "What"
i++; // increments i
Thank you, Captain Obvious. If I didn't know what `++` does, I shouldn't be here. The useless comment takes up space, wastes bytes, and insults the reader's intelligence.
The Lying Comment
// Returns true if user is admin
return false;
The code changed. The comment didn't. Now you have a comment that lies blatantly and misleads you. Trust the code, never the comment.
The Apology
// God forgive me for this, but the deadline is today
eval(input);
This comment is a cry for help. It doesn't explain the code, it confesses a crime. If you find this, run.
The Eternal TODO
// TODO: Refactor this urgent
(Commit date: 4 years ago)
"Urgent" is a relative concept in software development. This TODO is now part of the system architecture. It's a historical monument.
The Biography
// Created by John in 2015. Modified by Mary in 2016. Broken by Peter in 2018.
Git blame exists for this, people. We don't need a family tree in the file header.