On Comments

Karan Chawla / April 15, 2021

1 min read

Don't comment bad code — rewrite it.

Comments are not like Schindler's list. They are not "pure good". The proper use of comments is to compensate for our failure to express ourself in code.

Comments are always failures.

Inaccurate comments are far worse than no comments at all. They delude and mislead. They set expectations that will never be fulfilled.

Comments don't make up for bad code — Clear and expressive code with few comments is far superior than cluttered and complex code with lots of comments.

Explain yourself in code — Explain your intent with the code you're writing as opposed to writing a long comment around it.

Replace the temptation to create noise with the determination to clean your code. You'll find it makes you a better and happier programmer.

If you find yourself wanting to mark your closing braces, try to shorten your functions instead.

Don't offer systemwide information in the context of a local comment.

Subscribe to the newsletter

Get emails from me about future of technology, philosophy, and human behavior.

- subscribers