Note of CLEAN CODE chapter 4 - Comment

Comment do not Make up for Bad Code

You should clean the bad, clustered, disorganized and confusing codes instead of using comments to make up them.

Explain Yourself in the code

Sometimes you can create a new function whose name includes the comment

//check an employee eligible for full benefits
if(employee.flags && HOURLY && employee.age > 65){
    ...
}

if(employee.checkEligibleForFullBenefits()){
    ...
}

Good Comment

Legal Comment

Leave them in external documents or standard licenses, not as a contracts or legal tomes

Informative Comments

You can make the comments in the name when the comments are redundant

//return a responder being tested
protected abstract Responder responderInstance();

you can name it as responderBeingTested

// MATCH kk:mm:ss EEE, MMM dd, yyyy
Pattern timeMatcher = Pattern.compile("\\d*\\d*:\\d* \\w* \\d*, \\d*")

In this case, if this code is better and clearer, but it can be superfluous if it is moved to a class used to convert formats of dates and times.

Explanation of Intent

Show your intentions in codes

Clarification

If it is hard to understand what have some obscure function done and returned, it is nice to clarify the function, especially functions in a standard library you cannot alter.

Warning of Consequences

// do not run it unless you have a lot of time

You can use @Ignore() as well, but sometimes your languages do not support annotations.

You can also alert some thread unsafe functions

//SimpleDateFormat is thread unsafe, so we need to new it independently

Todo

• Things should be done but can’t at the moment
• Reminders to delet oa deprecated feature
• pleas for someone to look at a problem
• requests for a better name or a better change

Try to eliminate them as far as possible if you don’t want your code to be littered

Amplification

Amplify the importance of a function

Bad Comment

mumbling

Comments should be easy understood by everyone except merely author.

Redundant

Comments should not be longer than code.

Misleading

Make sure comments can match functions. If you comment some function returns a boolean value, then you might return false instead of throwing an exception when it should return false.

Mandated Comments

are not necessary

Journal Comments

If we have a source code control system, there is no need to save the long entries and add a comment to the star when it is editted.

Noise Comments

like
//Default Constructor

Scary Noise

/** the name */
String Name;

Don’t use a comment when you can use a function or variable

Position Marker

like this

//action//

It looks like a startling banner, but dont’t overuse it if you want to emphasize it otherwise people will ignore it automatically

Close Bracing Comment

If you use the type of comment, it is supposed to reduce your intendents and nested blocks

while(i < 10){
    if(a > 0){
        ...
    }//if
}//while

Attributions and Bylines

There is no need to do so because source code control system is good at doing so.

// added by john

Comment-out Code

It should be deleted.
If it is important, why should it be commented?

HTML Comments

It is hard to read as an adomination

Nonlocal Information

Make sure your comments are near the functions they reveal

Too much information

Inobvious comments

Don’t make your comments which require a comment to explain

Function Header

A short Function does not require a comment, and just writing it to the function name is better

Javadoc in Nonpublic Functions

They are not generally useful cuz they are not for public consumption.