Comments play an important role in the code, but have you ever thought about how to write them well?

1. Comments are meant to beautify bad code

Why do we need to write comments? Generally, if a piece of code needs to write comments to understand it, then this is a very dangerous signal. When writing our code, we should do it without writing comments. Just read the code and you will be able to understand it clearly. If you know what the code is going to do, let the code explain itself;

2. Good notes

2.1 Informative Notes

You can add comments to methods, classes, or variables to tell future readers what this means

2.2 Comments explaining the intent of the code

Use code to explain a logic and why it is done, such as suddenly defining a variable, or catching an exception that may be thrown by a method, explaining the exception

2.3 Explanation of the code

For example: sometimes comments translate the meaning of some obscure parameter or return value into some readable form.

assertTrue(bb.compareTo(ba)==1);//bb>aa
assertTrue(a.compareTo(b)==-1);//a<b

2.4 Cautionary Notes

Comments are useful to warn other programmers of a consequence, for example:

fun getDataFormat(): SimpleDateFormat {
    // SimpleDateFormat不是线程安全的，所以我们需要每次创建新的实例
    val df = SimpleDateFormat("yyyy-MM-dd")
    df.timeZone = TimeZone.getTimeZone("GMT")
    return df
}

2.5 ALL

Use TODO comments in the idea, the place where TODO is used will be highlighted, which can be a good reminder of the work that should be done after

TODO is a job that programmers think should be done, but for some reason has not done it yet . It might be a reminder to remove an unnecessary feature, or to call attention to an issue. It might be a plea for a good name, or a prompt for revisions that depend on a planned accident.

3. Bad Notes

3.1 Notes to yourself

If you feel like you should or because the process requires it to add comments, that's a no-brainer. Comments should be for the reader to see, not for themselves.

3.2 Pointless comments

What's the point of such code, such code that can be understood at a glance, writing comments is a waste of time and pollutes the page

 //如果count等于1，执行登录功能，如果对于二，执行注册功能
        if (count == 1){
            System.out.println("登录");
        }else if (count == 2){
            System.out.println("注册");
        }

3.3 Misleading comments

The comment says to return the password, but the code is different from what the comment says, probably because the code iterates many times, but the comment doesn't keep up

/***
 * 返回密码
 */
public String getPassword() {
    return account;
}

3.4 Commenting for the sake of commenting

What is a comment and a comment, for example, some people add a long list of documentation comments where there is no need to add comments

Like this, adding a comment to the get method, the six lines of this comment are pure waste of space.

3.5 Commented out code

Sometimes when we write the code, we find that there seems to be a problem with the writing, or the function needs to be changed, and the code needs to be changed. We often may not delete the original code, thinking that this code may be useful later, so It is a bad habit to use comments instead of deletions. The code that is commented there is often isolated for a period of time, and you forget to delete it, and your colleagues, seeing the code you commented, do not know why you want to comment, and also Don't dare to delete your code, so the code in this comment will always accompany the project; therefore, if you don't need this code, you can delete it with confidence. Do you think it will be troublesome to rewrite it in the future? So what do you think git is used for?

3.6 Unexplained Comments

Comments should be understood by reading comments when the code is difficult to understand. If the comments are not clear, do you still need comments? That's obviously ridiculous, so after the comments are written, read them at the end to see if they can explain the code well.

The way to clean code - comments