Should a comment be written in the code? _ Related Tips

This is a very controversial topic when many seniors are supposed to write more notes, when the web is full of jokes about programmers who never write notes. As a title party, let me revise my point of view: I think that if the code is good enough, most of the annotations are redundant, and we should replace more annotations by writing better code.

Annotations do have their uses, but in most cases, programmers misuse annotations. I am opposed to the annotations that are mixed with code, and I think that annotations should be independent of the code-often referred to as documents.

Take a look at the following code.

Copy Code code as follows:

/*/static/market/checkout.js

2014.7.2 Create by Orzfly
2014.7.29 Update by Jysperm:fixbugs

TODO: There are so many annotations in this code that you need to remove some--jysperm
*/

var raw_products = req.query[' products '].split (', ');

An array of commodity IDs
var products = []

Filter each parameter
for (var i = 0, i < Raw_products.length, i++) {
if (!raw_products[i])
Return

There's actually a space in the data from the front.
if (!raw_products[i].trim ())
Return

/* 2014.7.22: You can now use a non-numeric ID
Skip non-numeric entries
if (isNaN (Raw_products[i].trim (). toFixed ()))
Return
*/

Products.push (Raw_products[i].trim (). toFixed ());
}

Total Amount
var sum = 0;

Calculate the total amount of money for each item
for (var i = 0, i < Products.length, i++) {
Look up commodity information from the database
var data = Db.product.byID (Products[i]);

TODO: Who's going to write about the things you didn't find?

Add the price of a commodity to the total amount of money, A + B is an abbreviation for a = a + b
sum + + Data.price;
}

You spent half the time reading the notes, this is a waste of life, with every line of comment in the code increases the cost of reading the code-even if the reader has learned the spirit of the annotation and increases the cost of maintenance: the person who modified the code had to modify it along with the annotation- And you're not sure if he's going to do it.

So you should add a comment only when it is necessary, and it should be concise. Annotations should not explain what a piece of code is doing, because this is something that every qualified programmer should know, but should explain why the code does it.

This leads to several obvious annotations that should not be added:

Information that should be recorded by the version control system, comments on the code, and TODO that are not important.

The code is not all, a bit more reliable project, should have its own version control system, in addition to recording code differences, there should be work orders and Issue functions.
People who read the code usually don't need to understand the grievances between several programmers, and many times they don't care about the history of the code, which only drags the code ever longer.

Obsolete code

Deprecated code should be deleted, which can affect reading very much, and they are generally very long.
In most cases, deprecated code will not come in handy, and even in a few cases, you can find them from the version control system.

Explanation of variables and function names

In this case obviously you need a more appropriate name, and if the identifier has a relatively small effect, you can use a longer name to accommodate more information.

For example, in the above:

Products should be changed to products_id
Sum should be changed to Total_amount
Data should be changed to Product_record
Explanations of grammar, and obvious things

For example, "to add the price of a commodity to the total amount of money, A + b is a = a + b abbreviation", which is clearly what any one knows.

Perhaps someone would like to comb the idea by writing such a note:

Copy Code code as follows:

Filter Parameters:
Remove the space in the ID
Remove non-numeric ID
Cycle every commodity:
Go to the database, check the records.
Add the price of a commodity to the total amount of money

But when the code is finished, remember to erase it.

The generalization of logical blocks

For example, "filter each parameter" and "Calculate the total amount of money for each item" In this case, you usually do not abstract the logic, as shown below:

Copy Code code as follows:

First there are 25 lines of code to do things a
And then there are 5 lines of code to do things B
Here are 90 lines of code to do things C
Finally, there are 45 lines of code to do things D

This causes you to need some comments to split the four parts. If these four parts are a function call, then the function name itself is an explanation of the logic, the reader can quickly find function B, without having to search the first 25 lines to do the five elements of B.

In conclusion, my comments on the improvement of this code are as follows:

Copy Code code as follows:

var Filterproductid = function (raw_products_id) {
result = []

Raw_products_id.foreach (function (product_id) {
if (product_id and Product_id.trim ())
Products_id.push (Product_id.trim (). toFixed ());
});

return result;
};

var getpriceofproduct = function (ID) {
var Product_record = Db.product.byID (Products[i]);

if (Product_record)
return product_record.price;
Else
return 0;
};

var products_id = Filterproductid (req.query[' products '].split (', '));
var tatol_amount = 0;

Products_id.foreach (function (product_id) {
Tatol_amount + + getpriceofproduct (product_id);
});

While I am supporting my view with a fictional, deliberately fabricated code, I believe that in actual projects, the same can be done by improving the code to reduce annotations and, in general, save more time and effort.