How to solve two major problems at once, without writing comments, and without being complained by others?

Reference: Alibaba Cloud Developer Community

guide

Every programmer hates two things, reading code without comments, and writing comments to code .

So how to solve two major problems at once, without writing comments, and without being complained by others?

"If our programming languages ​​were expressive enough, or if we had the talent to subtly wield those languages ​​to express our intent, we would not need comments very much—perhaps not at all." ——Robert C. Martin "Clean Code"

If If the programming language is expressive enough, or we are good at expressing intent in these languages, then we don't need annotations so much, or even at all.

How to solve the two major problems of programmers at once, without writing comments, and without being complained by others for not having comments?

Why reduce the amount of comments in the code?

• The existence of comments shows that the logic of the current code is not particularly clear. Without additional explanations, others may not be able to understand the intent.

• Comments are difficult to maintain. After the development of a task is completed, the comments distributed in the task will most likely not be updated. As time goes by, the code becomes more and more complex, and the information in the comments may not be able to accurately feed back the current logic. up.

• The process of reducing comments is also a process of re-examining the code structure and streamlining the code.

So what are the bad comments, and what can be done to get rid of them?

1. Useless comments

The back-end cannot trust any information passed in by the front-end, so when writing code, it cannot trust any capabilities. Even for the simplest operation, a comment should be added to explain the details of the operation.

public void addInfo(Info info){
    
    
  ...
  //向信息列表中追加信息内容
  this.infoList.add(info);
  ...
}

Believe in the ability of colleagues, common operations, even if there is no comment, you can understand your intentions through the context.

Two, rambling notes

The code logic is too convoluted. In order to prevent it from becoming God's little secret, write a comment so that it will not become God's little secret.

public void addInfos(List<Info> infos){
    
    
  ...
  //如果Infos没有，就直接返回，如果Infos只有一个，那就删除数据库的信息，再写入。。。
  ...
}

It seems that there is an annotation, and I no longer worry about becoming God's little secret. But once a small amount of code far away from the annotation is modified, it will cause God to re-exclusively share the secret of this code.

"Comments Do Not Make Up for Bad Code" - Robert C. Martin "Clean Code"

comments do not optimize bad code

Complex comments indicate that the logic of the code itself may be problematic. It may be more meaningful to sort out the logic diagram and reorganize the model of the state machine than to write complex comments.

From the seven possible pathways and multiple execution strategies on the left to the clear and simple secondary judgment + execution process on the right, the status and changes are clear and simple.

3. Notes instead of code layering

The development framework emphasizes high cohesion and loose coupling. Therefore, my functions should also be highly cohesive. Functions that can be written together should not be separated into multiple functions. In order to prevent someone from being unable to understand the logic of this code, add comments.

// 判断是否活跃用户
if((customer.getLastLoginTime().after(dateUtils.minusDays(new Date(),15)) && customer.getCommentsLast30Days() > 5) 
    || orderService.countRecentDaysByCustomer(customer,30) > 1)

On the one hand, unreasonable layering adds redundant comments, and also makes the entire code more maintainable. If the logic for judging active users changes, wouldn’t it be necessary to press Ctrl+F to find the full text? Once a place is missed, a bug will arise.

Reasonable function extraction can strengthen the logic of the code. Instead of seeing complex Boolean calculations, isXXX is my favorite.

private boolean isActivate(){
    
    
  return getLastLoginTime().after(dateUtils.minusDays(new Date(),15)) && getCommentsLast30Days() > 5) 
    || orderService.countRecentDaysByCustomer(this, 30) > 1)
}

if (customer.isActive()){
    
    
  ...
}

4. Unintelligible comments

In order to allow God to enjoy the secrets of the code more quickly, even the comments quickly surrendered to the arms of God's secrets.

public synchronized void setFormatter(Formatter newFormatter) {
    
    
    checkPermission();
    // 检查是否空指针
    newFormatter.getClass();
    formatter = newFormatter;
}

The comments here seem to be in no way connected to the code behind. But the function provided by java can explain the intention of checking the null pointer more clearly Objects.requireNonNull()than the method used by the author , and it can also kill this kind of unintelligible code. getClassSimilarly Collections, StringUtilsthe following series of functions.

Although there are so many bad comments and no comment methods for these comments, as ChatGPT's answer:

Writing code without comments is challenging because comments help the reader understand the purpose and workings of the code. Here are some suggestions for writing code without comments:

1. Keep your code concise: Concise code is easy to understand, making it easier to read and understand.

2. Use descriptive names: Using descriptive variable and function names can help readers understand the purpose of the code.

3. Follow a consistent coding style: Use consistent indentation, spacing, and naming conventions to make your code easier to read.

4. Break the code into small pieces: Breaking the code into small pieces can help the reader understand the purpose and function of the code.

5. Write self-describing code: Writing self-describing code helps readers understand the purpose of the code, for example, using meaningful variable and function names. Although these tips may help you write more readable code, comments are still an important part of writing high-quality code. When you must write code without comments, follow these recommendations as much as possible.

Although uncommented code may not be available in the end, it is very worthwhile to reduce comments, examine our code structure, and let the code become God's little secret one day later.