Notes-a double-edged sword
What is a comment and why should there be a comment?
In my opinion, comments are a supplement to the code . That is to say, comments are to make up for the failure of your code in expressing meaning . So I think you should not write too many comments except when necessary. If your code After writing too many comments, should I reflect on myself, my own code is so illogical? Just overthrow and refactor the code to make your code more logical and readable.
1. Don't let yourself be dependent on comments
Many programmers did not consider the overall structure and logic of the project before writing the code, but just picked up the keyboard to write. As a result, they stumbled and wrote a lot of comments, and when they ran it, they found that the results were correct. So I feel that everything is going well. I don’t know that this is using comments to cover up the bad smell of poor-quality code. In the long run, the code specifications will be left behind, and the logic ability will also be greatly reduced. So when you write a series of comments, you should reflect on yourself. Failure to express.
Even if the bad code is well commented, it is equivalent to spraying perfume in the toilet, treating the symptoms rather than the root cause.
2. What is a bad comment
2.1 Why use comments for things that can be explained by code?
//To calculate the area.a is length,b is width
public double fun1(double a,double b)
{
double c=a*b;
return c;
}
The above is an extremely foul-smelling example, most people will not really write this. But I believe that many people will also have this situation to varying degrees. It is clearly able to use concise variable names and good code logic to present Why should I add comments to the things that come out!!!. I believe that the following code can be understood without comments.
public double calculateRectangleArea(int length,int width)
{
double area=length*width;
return area;
}
2.2 Talk nonsense
//try and catch the IOExceptiopn
try
{
properties.load(resourceAsStream);
dataSource=DruidDataSourceFactory.createDataSource(properties);
} catch (IOException e)
{
e.printStackTrace();
}
What is this kind of code doing? Is it written to ordinary people who don't understand coding? I believe that a programmer knows what it is doing, so don't waste your precious time doing these boring things.
2.3 Commented out code
Graphics graphics = bufferedImage.getGraphics();
graphics.setColor(Color.WHITE);
// graphics.setColor(Color.BLUE);
graphics.fillRect(0, 0, length, width);
graphics.setColor(Color.YELLOW);
graphics.drawRect(0, 0, length - 1, width - 1);
In the process of writing code, many programmers will often comment out some code for modification. This is understandable. But when you have completed this code, please delete the commented code . If this is a completed code How should the project, subsequent maintainers and developers treat these commented codes? This will cause them a lot of trouble.
3 What is the necessary code
3.1 Legal and version information
Sometimes when the company writes the code, the relevant information is required to be placed at the beginning of the code.
3.2 Explanation and agreement
string transCharToString(char ch);
string codeSource;
map<string, int> tokens;//identifier is 1,reservedWord 2,digit 3,borderSymbol 4,operator 5
When writing code, the return value of our method or some variables need to be expressed in a simpler way. For example, in the above code, in the map structure, we agree that 1 means identifier, 2 means reserved word, etc. Compared to using strings directly, this method is more concise.
3.2 Warning and emphasis
Sometimes the code may have some bad consequences, or a certain part is particularly important.At this time, you can use comments to inform later maintainers and developers to avoid serious consequences.
3.3 TODO notes
//TODO
@ApiOperation("通过用户id组来删除用户")
@DeleteMapping("/deleteUsers")
public Integer deleteUsers(@RequestBody Map userIds)
{
return null;
}
The development of a project is often long.Some functions or interfaces have been defined in the format, but they have not been completed. You can add a TODO to remind yourself to complete it.