Clean Code Applied to JavaScript — Part IV. Comments

In this article, we’ll discuss a controversial topic when developers write clean code: comments.

Some people think it’s a good practice to comment code, but some people think it’s a bad practice.

First of all, there are no absolute rules on whether your code needs to be commented. It all depends. In fact, in many cases, annotations don’t help software development because there are already many tools that are better than annotations. In other cases, comments can interfere with code development now or code reading in the future. Therefore, no comments is a best practice in these cases.

On the other hand, it may be good practice to add comments, for example, because while the public API documentation can be used to understand how a library is used externally, it does not explain its internal code logic.

Next, I’ll summarize some of the common ways in which incorrect comments can interfere with code reading. In practice, avoid incorrect comments to improve the quality of your code.

Annotate only content with complex business logic

The purpose of comments is to help the programmer better understand the program or business logic, because some logic is too complex for the programmer to understand by reading the code directly. But often code comments don’t describe the algorithm and logic, they just explain what the code does. The real logic of a program still needs to be understood by reading the source code, but at the same time, good code is itself a comment and is often as it is seen. Therefore, adding comments to code is possible, but usually not necessary.

There are exceptions, such as when there is a particular business logic in the program that we as developers don’t know about. For example, credit card business logic, insurance business logic and so on. Without explanation, it’s hard to understand the purpose of this code when you read it. The following example shows details and unnecessary comments in most code operations. But the last comment is useful because it is not describing programme-level operations, but rather an explanation of business logic.

function convert(data){
 // The result
 let result = 0;

 // length of string
 const length = data.length;

 // Loop through every character in data
 for (let i = 0; i < lenght; i++){
   // Get character code.
   const char = data.charCodeAt(i);
   // Make the hash
   result = (result << 5) - result + char;
   // Conver to 32-bit integerresult &= result; }}Copy the code

In the above code, most of the comments don’t do anything and instead interfere with our reading of the code, the equivalent of which is shown below.

function convert(data) {
  let result = 0;
  const length = data.length;

  for (let i = 0; i < length; i++){
    const char = data.charCodeAt(i);
    result = (result << 5) - result + char;
    result &= result; // Convert to 32-bit integer}}Copy the code

Avoid logging comments

Date-based journaling comments record changes in file content over time. In the past, when versioning tools were lacking, this kind of comment made sense. But this is no longer recommended. This logging should be handed over to a version control tool (such as Git), so you don’t need invalid code, such as comments like this, which add redundancy and uncleanliness to your code. If you need to view this kind of information, you can use git logs to obtain history records.

Here is a code with logging comments, and a clean version without comments.

/** * 2018-12-20: Removed monads, didn't understand them (CC) * 2018-10-01: Improved using special mondas (JS) * 2018-02-03: Removed type-checking (LI) * 2017-03-14: Added add with type-checking (CC) */
 function add(a, b) {
   return a + b;
 }
Copy the code
function add(a, b) {
   return a + b;
 }
Copy the code

Avoid using comments to mark locations

You should avoid using comments for location marking, as this usually just makes your code redundant. Name variables and functions correctly, optimize the code structure, and increase the readability of the code.

The code below is an example with a location-tagged comment and its uncommented version. As you can see, the use of such annotations is outdated, and there is no need to create these tags in the source code.

///////////////////////////////
// Controller Model Instantiation
///////////////////////////////
controller.model = {
  name: 'Felipe'.age: 34
};

///////////////////////////////
// Action Setup
///////////////////////////////
const actions = function() {
  // ...
};
Copy the code
controller.model = {
  name: 'Felipe'.age: 34
};

const actions = function() {
  // ...
};
Copy the code

conclusion

The need for comments is one of the most controversial topics among software developers today, with some saying they are necessary and others saying they are not. Extremes are never the best choice in any life choice, and software development is no different.

So, in this article, you’ve summarized three approaches to commenting code. However, if we are creating a public API, it might be interesting to write comments because they can be thought of as documentation for the API.

A very bad habit is to add comments to every line of code. Many beginning programmers get into the habit of commenting out every line of code as if they were taking notes when learning to write code.

The difference between taking study notes and adding code comments during software development is huge and should not be confused.

Finally, let’s review the main points of this article:

  • Annotate only content with complex business logic
  • Avoid logging comments
  • Avoid using comments to mark locations

Related articles

  • The Way to clean JavaScript Code – Functions
  • Simple practices for writing clean React code
  • Simple tips for writing a compact React component

Click the public account KooFE Front-end Team