loading...
Cover image for Clean Code Applied to JavaScript — Part IV. Comments

Clean Code Applied to JavaScript — Part IV. Comments

carlillo profile image Carlos Caballero Originally published at carloscaballero.io ・4 min read

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

Discussion

pic
Editor guide
Collapse
thomasjunkos profile image
Thomas Junkツ

Absolutely this.

I would rephrase

Only comment things that have business logic complexity

to

Comment non obvious decisions

Because there may be cases where

  • you have (mathematical) knowledge which the future reader of your code might not have

  • your code isn't correct but a smart approximation which is good for now

  • your code isn't correct and no approximation to anything but for reasons outside the code it is written like that. I actually did this where data was sometimes deliberately overwritten with null which was wanted behaviour. So I commented this as

    //Customer decision: do this and that else null the value

And when a furture reader stumbles over this line of code he saves time not discussing this point any further

Collapse
rsuttles58 profile image
Rob Suttles

While comments on every line are definitely an eye sore, aren't positional markers a tool to improve readability and grouping of code? I'm admittedly a junior/mid-level dev, but have received complements for the way that I have utilized positional markers in my code/scripts. I want to add that I didn't care for the way the positional markers were styled here but overall I think they improve readability for other users.

Far too often, I see zero commenting in code. If there had to be one extreme or another I would prefer verbose code commenting, particularly in larger development teams where a significant number of junior or developers new to the team will be reviewing code and do not understand business logic and process context.

Collapse
fly profile image
joon

I agree with all the points, except the part that states that comments should only be used when there is 'business level complexity'.
Don't get me wrong - I'm not advocating using comments to the point of the example - that definitely should be avoided at all costs. But it also seems like a rather extreme case.

Personally I add comments to code like javascript one-liners that are almost equivalent to machine code when it comes to readability, or functions that seem simple but have more use-cases than meet the eye.

Just adding my thoughts to the topic :)

Collapse
ashleyjsheridan profile image
Ashley Sheridan

My rule for code comments is this: comment only on the 'why' never the 'what', unless the 'what' is a regex, in which case you can comment the hell out of it :P

Collapse
havespacesuit profile image
Eric Sundquist

I love adding the occassional todo: comment, when I'm busy and see something that needs improved. Usually it is outside of the current task I'm working on, so I'll note it and move on.

Collapse
jabin753 profile image
Jabin Cuevas

Thanks for sharing this serie. I'll improve my code right now. Saludos :D

Collapse
carlillo profile image
Carlos Caballero Author

Thanks Jabin! 😜😜

Muchas gracias 🙃