3. Comments - tuansondinh/clean_code GitHub Wiki

In short: Try to avoid comments. Try to express to yourself in the code!

3.1 Comments do not make up for bad Code

Clean your code, instead of writing comments to make up for it!

3.2 Express yourself in/with the code

BAD:

// Check to see if the employee is eligible for full benefits
if ((employee.flags & HOURLY_FLAG) && (employee.age > 65))

GOOD:

if (employee.isEligibleForFullBenefits())

3.3 Good Comments

The only good comment is the one you don't have to write.

3.3.1 Legal Comments

Should be hidden by the IDE and refer to a standard license or an extern document to keep it short.

3.3.2 Informative Comments

See example in 3.2.

3.3.3 Explanation of Intent

Use comments to explain why you have decided for a specific solution.

3.3.4 Clarification

WIP

3.3.5 Warnings for Consequences

Use comments to warn for consequences. Example:

// Don't run unless you have some time to kill.
public void _testWithReallyBigFile(){...}

3.3.6 TODO-Comments

TODO-Comments are no excuse to leave bad code in the system. Check your code regularly and delete the TODOs, which you can.

3.3.7 Amplification

Use comments to amplify the importance of something.

3.3.8 Javadocs in Public APIs

Use Javadocs only for public API. But keep in mind:

"Javadocs can be just as misleading,nonlocal, and dishonest as any other kind of comment." S.59

3.4 Bad Comments

3.4.1 Avoid Mumbling

"If you decide to write a comment, then spend the time necessary to make sure it is the best comment you can write." S.59

"Any comment that forces you to look in another module for the meaning of that comment has failed to communicate to you and is not worth the bits it consumes." S.60

3.4.2 Avoid Redundant & Noise Comments

Don't comment, if the code is self-explanatory and if the code does not provide any new information.

3.4.3 Avoid Misleading Comments

Try to be precise as possible to avoid misleading comments.

3.4.4 Avoid Mandated Comments

Not every function must have a JavaDoc. Not every variable must be commented. If the comments aren't useful, avoid them to keep the code clean.

BAD:

 /**
 *
 * @param title The title of the CD
 * @param author The author of the CD
 * @param tracks The number of tracks on the CD
 * @param durationInMinutes The duration of the CD in minutes
 */
 public void addCD(String title, String author,
 int tracks, int durationInMinutes) {
 CD cd = new CD();
 cd.title = title;
 cd.author = author;
 cd.tracks = tracks;
 cd.duration = duration;
 cdList.add(cd);
}

3.4.5 Avoid Journal Comments

Don't use them, because we have source code control systems like Git.

3.4.7 Explain through Function- or Variable-Name instead of comment

3.4.8 Position Markers

Use Position Markers sparingly and only when the benefit is significant. (e.g. gathering functions beneath a marker)

"If you overuse banners, they’ll fall into the background noise and be ignored." S.67

Avoid noisy stuff like below:

BAD:

// Actions //////////////////////////////////
...

Better:

// Actions
...

3.4.9 Avoid Attributions and Bylines

Let source code control systems do the work. Don't store attributions in comments.

BAD:

/* Added by Son*/

3.4.10 Avoid Commented-Out-Code

Avoid Commented-Out-Code, because others will be afraid to delete them.

"So commented-out code gathers likedregs at the bottom of a bad bottle of wine." S.68

3.4.11 Avoid HTML Comments (Messy and hard to read)

3.4.12 Avoid Nonlocal Information

"If you must write a comment, then make sure it describes the code it appears near." S.69

3.4.13 Avoid Too Much Information

"Don’t put interesting historical discussions or irrelevant descriptions of details into your comments." S.70