Wednesday, March 11, 2009

Three Rules for Comments

My first rule for comments:
If you can possibly express your ideas in the code, you must express them in the code and delete the comment; comments are for things not possible to describe in code.

The second rule is:
If you copy and paste code, do not copy and paste the comments. Comments that are duplicated and wrong have never been helpful.

Rule three is:
Commented-out code doesn't really exist, so deleting it is harmless at worst, and quite often improves the readability of the rest of the code.

Any time you can delete a superfluous comment, it's a good day.
Any time you can change code to make the comments superfluous, it's an even better day.
Any time you find code so clear it doesn't need comments, it's a good time to be alive.