Introduction

In this post, we will describe one of the topics that most debate raises among developers when they are dealing with the issue of clean code.

Many developers think that comments are good practices while others think totally the opposite, that is, to apply comments are bad practices.

Sorry to tell you that there are no absolute rules, everything depends on the case. The truth is that there are a number of cases in which the comments do NOT contribute to software development because they have been replaced by other tools that perform that function better than that of applying comments. In other cases, comments may cause noise to the source code that we are developing, or that we will be reading in the future. Therefore, in those cases, the ideal is to have no comments.

On the other hand, there may be cases in which comments are good practices, such as the documentation of a public API in which to learn the behavior of a library, but not how it is developed.

In the next post, I will describe several practices in which comments produce noise and should not be applied in your code so that your code grows in quality.

Only comment things that have business logic complexity

Comments have to exist only to help programmers in explaining business logic that is complicated for programmers to understand. In no case, the comments describe the algorithm. We have to think that a good code is most of the time self-documented and therefore, the source code is understood with the fact of being read. Comments are an extra, not a requirement.

However, it can happen that in the algorithm there is a specific business logic that we do not know as developers. For example, operations with credit cards, with own insurance operations, etc. The following example shows the verbosity and unnecessary comments in most of them. However, the last comment would not be irrelevant since an operation is being carried out in the domain of the problem we are modeling and it would not hurt that this comment existed. This comment is not describing what is being done at the programming level but at the level 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 integer
   result &= result;
  }
}

The equivalent code would be the following, in this code it is observed that the comments did not add value, but produced noise to our code.

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
  }
}

Don't have journal comments

The comments as a journal were, and I hope it is not today, a tendency to know what had happened to the file over time. This could make sense in the past for lack of version control tools.

Today, this task should be delegated to version control software (I recommend using GIT). Therefore, there is no need for dead code, commented code, and especially journal comments.

To obtain this information you would only have to use the git log to get history command.

Below, there is a code with journal comments versus its cleaner version.

/**
 * 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;
 }

 function add(a, b) {
   return a + b;
 }

Avoid positional markers

You should avoid positional markers because usually just add noise. Let the functions and variable names along with the proper identation and formatting give the visual structure to your code.

The following code shows an example with positional markers and its clean version. You should think that these techniques of using comments are anachronistic from other times in which there was less tooling for developers. Nowadays, it is not necessary to create these marks in a source code, since they are only noise.

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

///////////////////////////////
//  Action Setup
///////////////////////////////
const actions = function() {
  // ...
};

controller.model = {
  name: 'Felipe',
  age: 34
};

const actions = function() {
  // ...
};

Conclusions

Comments are one of the most debated topics today by developers. Many developers believe that they are necessary and others that are not, extremes are never good in any decision in this life, and software development is no different.

Therefore, in this post I have tried to summarize three practices that make the code dirty by including comments. However, if we are creating a public API it may be interesting to write comments since we are documenting the API.

A bad practice applied by many teachers is to comment on each of the lines in production codes. This bad practice is inherited from when a junior programmer is being taught to code code, each line is commented on as a study guide.

However, the difference between having a study guide and commenting on each line of code in a production development is huge.

Finally, the points we have addressed are the following:

• Only comment things that have business logic complexity
• Don't have journal comments
• Avoid positional markers