Comments – Chapter 4

Comments Do Not Make Up for Bad Code

Don't leave a mess and then explain it away.

Explain Yourself in Code

Don't write a comment to explain what code does when you can simply make it a well named explanatory method.

Good Comments

Legal Comments

Copyrights and such are necessary from time to time.

Informative Comments

Explain things that may be unclear on the surface, such as a regular expression.

Explanation of Intent

Explain the why of a potentially difficult to understand decision.

Clarification

Translate into more clear language what is happening.

Warning of Consequences

Warn your fellow developers if there is danger to particular method.

TODO Comments

Make note to go back and resolve something that isn't complete from a functional or qualitative standpoint.

Public API Documentation

Make any public API methods well documented in the standards of the language so that consumers can clearly see your methods' intent.

Bad Comments

Mumbling

Complaining about a process or method isn't helpful.

Redundant Comments

Don't communicate something that is already clearly expressed in your code.

Misleading Comments

Don't write comments that tell a different narrative than your code.

Journal Comments

Source control keeps very good records of who changed what.

Noise Comments

Don't give useless or redundant information.

Don’t Use a Comment When You Can Use a Function or a Variable

Code is the best and first way you should express your intent.

Position Markers

Avoid using comments to break up sections of a code file. It may make sense to move those to their own classes or collapse them in regions.

Closing Brace Comments

Don't try to help fellow developers read.

Attributions and Bylines

See Journal Comments.

Commented-Out Code

Don't leave commented code in source. It's not helpful. Delete it.

Too Much Information

Don't clutter code with a bunch of noise.

Function Headers

Name your functions well enough that you don't need these.

Platform docs in private / internal code

Don't place platform API docs on methods and classes that are not being publicly consumed.