My take on commenting code – Explain why, not how

// That is the beginning of the article
Enter fullscreen mode

Exit fullscreen mode

Ohh rattling, could not have figured that one out if it wasn’t for the remark…

Simply kidding, although many code feedback I see are as helpful as a comb to a daring individual.


👋 Hey there! It has been some time since I’ve written something right here. Hope you are doing implausible!

Simply wished to come back again to put in writing a bit, so I’ll begin with a little bit rant about code feedback, as I see many new builders discover this complicated and stuffed with confusion.


PD: Earlier than persevering with I wish to make it clear that I am speaking about code feedback, not documentation feedback, which may be helpful.

Code feedback are meant so as to add extra context to your codebase, in case the code itself will not be sufficient (however usually code ought to be sufficient).

I wish to make an enormous emphasis on “when the code will not be sufficient”, as you must purpose to put in writing clear and readable code first, then refactor, refactor, after which if nonetheless wanted present a remark to additional clarify it.

Additionally, when writing code in an present codebase, both at work, on an open-source mission or no matter. There may be a typical or conference in place, which could require you to put in writing feedback. This have to be revered and adopted until you have got the authority to vary it.



Let’s break down some myths



It’s best to touch upon every part

const age = 21;            // Specify the age of the consumer
const title = "Bob";        // Set the title of the consumer
const yearsLeft = 84 - 21; // years of life left
const bananas = 'yum';     // I like bananas
Enter fullscreen mode

Exit fullscreen mode

That is one I hear fairly a bit. A number of the interns I’ve had had been shocked after I advised them to not deal with commenting code however as an alternative deal with making an attempt to put in writing readable code.

This was as a result of their lecturers advised them that they need to touch upon every part, the entire time.

It is fairly an excessive manner of feedback, on this vogue you’ll fill your code base with feedback that simply say “// Assign a reputation to the consumer” and so forth.



You shouldn’t remark in any respect

[][(![]+[])[+[]]+(![]+[])[!+[]+!+[]]+(![]+[])[+!+[]]+(!![]+[])[+[]]][([][(![]+[])[+[]]+(![]+[])[!+[]+!+[]]+(![]+[])[+!+[]]+(!![]+[])[+[]]]+[])[!+[]+!+[]+!+[]]+(!![]+[][(![]+[])[+[]]+(![]+[])[!+[]+!+[]]+(![]+[])[+!+[]]+(!![]+[])[+[]]])[+!+[]+[+[]]]+([][[]]+[])[+!+[]]+(![]+[])[!+[]+!+[]+!+[]]+(!![]+[])[+[]]+(!![]+[])[+!+[]]+([][[]]+[])[+[]]+([][(![]+[])[+[]]+(![]+[])[!+[]+!+[]]+(![]+[])[+!+[]]+(!![]+[])[+[]]]+[])[!+[]+!+[]+!+[]]+(!![]+[])[+[]]+(!![]+[][(![]+[])[+[]]+(![]+[])[!+[]+!+[]]+(![]+[])[+!+[]]+(!![]+[])[+[]]])[+!+[]+[+[]]]+(!![]+[])[+!+[]]]((!![]+[])[+!+[]]+(!![]+[])[!+[]+!+[]+!+[]]+(!![]+[])[+[]]+([][[]]+[])[+[]]+(!![]+[])[+!+[]]+([][[]]+[])[+!+[]]+(+[![]]+[][(![]+[])[+[]]+(![]+[])[!+[]+!+[]]+(![]+[])[+!+[]]+(!![]+[])[+[]]])[+!+[]+[+!+[]]]+(!![]+[])[!+[]+!+[]+!+[]]+(+(!+[]+!+[]+!+[]+[+!+[]]))[(!![]+[])[+[]]+(!![]+[][(![]+[])[+[]]+(![]+[])[!+[]+!+[]]+(![]+[])[+!+[]]+(!![]+[])[+[]]])[+!+[]+[+[]]]+([]+[])[([][(![]+[])[+[]]+(![]+[])[!+[]+!+[]]+(![]+[])[+!+[]]+(!![]+[])[+[]]]+[])[!+[]+!+[]+!+[]]+(!![]+[][(![]+[])[+[]]+(![]+[])[!+[]+!+[]]+(![]+[])[+!+[]]+(!![]+[])[+[]]])[+!+[]+[+[]]]+([][[]]+[])[+!+[]]+(![]+[])[!+[]+!+[]+!+[]]+(!![]+[])[+[]]+(!![]+[])[+!+[]]+([][[]]+[])[+[]]+([][(![]+[])[+[]]+(![]+[])[!+[]+!+[]]+(![]+[])[+!+[]]+(!![]+[])[+[]]]+[])[!+[]+!+[]+!+[]]+(!![]+[])[+[]]+(!![]+[][(![]+[])[+[]]+(![]+[])[!+[]+!+[]]+(![]+[])[+!+[]]+(!![]+[])[+[]]])[+!+[]+[+[]]]+(!![]+[])[+!+[]]][([][[]]+[])[+!+[]]+(![]+[])[+!+[]]+((+[])[([][(![]+[])[+[]]+(![]+[])[!+[]+!+[]]+(![]+[])[+!+[]]+(!![]+[])[+[]]]+[])[!+[]+!+[]+!+[]]+(!![]+[][(![]+[])[+[]]+(![]+[])[!+[]+!+[]]+(![]+[])[+!+[]]+(!![]+[])[+[]]])[+!+[]+[+[]]]+([][[]]+[])[+!+[]]+(![]+[])[!+[]+!+[]+!+[]]+(!![]+[])[+[]]+(!![]+[])[+!+[]]+([][[]]+[])[+[]]+([][(![]+[])[+[]]+(![]+[])[!+[]+!+[]]+(![]+[])[+!+[]]+(!![]+[])[+[]]]+[])[!+[]+!+[]+!+[]]+(!![]+[])[+[]]+(!![]+[][(![]+[])[+[]]+(![]+[])[!+[]+!+[]]+(![]+[])[+!+[]]+(!![]+[])[+[]]])[+!+[]+[+[]]]+(!![]+[])[+!+[]]]+[])[+!+[]+[+!+[]]]+(!![]+[])[!+[]+!+[]+!+[]]]](!+[]+!+[]+!+[]+[!+[]+!+[]])+(![]+[])[+!+[]]+(![]+[])[!+[]+!+[]])()((![]+[])[+!+[]]+(![]+[])[!+[]+!+[]]+(!![]+[])[!+[]+!+[]+!+[]]+(!![]+[])[+!+[]]+(!![]+[])[+[]]+([][(![]+[])[+[]]+(![]+[])[!+[]+!+[]]+(![]+[])[+!+[]]+(!![]+[])[+[]]]+[])[+!+[]+[!+[]+!+[]+!+[]]]+[+!+[]]+([+[]]+![]+[][(![]+[])[+[]]+(![]+[])[!+[]+!+[]]+(![]+[])[+!+[]]+(!![]+[])[+[]]])[!+[]+!+[]+[+[]]])
Enter fullscreen mode

Exit fullscreen mode

That is the other aspect of the spectrum, and for my part, can also be actually excessive. There are a number of circumstances the place commenting code is actually helpful. Or to know code like the instance above, utilizing JSFuck. (It runs alert(1))

For instance, I’ll develop on this, explaining WHY a chunk of code is required.

In my case, I attempt to put in writing as few feedback as attainable, and if I remark one thing I often clarify “WHY” not “HOW”.

For instance, as an alternative of writing:

// Resets the canvas
canvas.reset(); 
Enter fullscreen mode

Exit fullscreen mode

You could possibly put it this manner:

// We reset the canvas right here so we do not draw over the presently rendered drawing 
canvas.reset();
Enter fullscreen mode

Exit fullscreen mode



 The place to place feedback?

That is subjective, and is determined by every language, mission and our personal requirements. However usually feedback:

// Remark
const code = "";
Enter fullscreen mode

Exit fullscreen mode

  • or after the code in the identical line.
const code = ""; // Remark
Enter fullscreen mode

Exit fullscreen mode

I’ve additionally heard folks put the feedback after the code, which for me is a bizarre place to place them, as code flows from prime to backside, it is senseless to me to place the remark afterwards. However once more, that is as much as you and the codebase requirements and conventions.


Now let’s lay down a listing of a number of the professionals and cons:



Professionals

  • Provides extra context to your code
    • For instance explaining why we would want that piece of code in a specific place
  • Helps to create a thoughts map (in some circumstances)



Cons

  • Provides noise
    • Could make your code look messy, making it extra tedious to learn by the precise code
  • Provides one other dependency
    • You will must hold them up to date because the code modifications, in any other case it may be complicated as hell. Feedback can develop into outdated reasonably rapidly
  • You’ll are inclined to learn the feedback first, then the code, which could situation you.



 Let’s take a look at some examples



 Dangerous feedback (or ineffective)

class Consumer {
  // Returns the title of this consumer
  namedWhat() {
     ...
  }
}

const title = consumer.namedWhat(); // Get the consumer's title

// Provides merchandise to listing if it is not current within the listing
addItemToList() {
    if (this.merchandise && !this.gadgets.some((it) => it.id == this.merchandise.id)) {
        this.gadgets.unshift(this.merchandise);
    }
}
Enter fullscreen mode

Exit fullscreen mode

These feedback provide little to no worth in any respect, they simply add noise. Naming strategies and variables appropriately provide far more worth than feedback just like those above.

The above instance may very well be made so much clearer by renaming some strategies, and altering some feedback so that they clarify why we’d like it as an alternative of what it does (that may be defined by the strategy title)

class Consumer {
  getName() {
     ...
  }
}

const title = consumer.getName(); 

// this methodology is required as a result of if this.gadgets doesn't include this.selectedItem, the selector won't show the chosen merchandise. 
// Through the use of this methodology we guarantee the chosen merchandise is displayed
ensureSelectedItemIsOnList() {
    if (this.hasSelectedItem && !isSelectedItemOnList()) {
        this.gadgets.unshift(this.selectedItem);
    }
}
Enter fullscreen mode

Exit fullscreen mode

Renaming the addItemToList methodology to ensureSelectedItemIsOnList, and creating strategies to raised clarify the code, and likewise including an evidence on why this methodology is required, makes it much more clear. We all know, by the strategy title, that it’ll be certain that the chosen merchandise is on the gadgets listing. Then the remark provides a bit extra context on why it is wanted: “Ensuring the chosen merchandise seems on the selector, even when it is not within the loaded listing of things.”

You may be pondering



How can the above remark profit us as builders?

Nicely, it is fairly easy, as an example you’re employed on the piece of code proven above, you construct the selector, discover the error with the chosen merchandise not displayed if not contained inside gadgets. You repair it and add the remark to elucidate why you added that piece of code.

Then you do not return to that code in 6 months or a 12 months, and then you definately or one other developer must construct a brand new selector. And naturally, you construct it from scratch and stumble throughout the identical bug. Then you definitely go to the unique selector to see what’s totally different. Then you definitely see the remark which kindly explains the answer to the bug.

If the remark was not there, you would need to as soon as once more remedy the bug by yourself, which might take no time in any respect or fairly a little bit of time, relying on the bug.

So, by having the remark, it makes it fairly straight forwards. Consider me, the code above is extracted from one in every of our initiatives, and that remark has saved us an entire lot of labor.



Abstract

We have lined some frequent myths and misconceptions round feedback, and we have seen examples of helpful and ineffective feedback. And defined why they’re thought-about ineffective and helpful.



 Key ideas to remove

  • Prioritize writing readable code
  • Remark why not how
  • Feedback can develop into outdated quick, and do extra hurt than good



 Query for you

What’s your tackle code feedback? Do you utilize them, and if that’s the case when and why?


That is all for this rant, I hope I’ve made sense and eliminated some confusion round feedback.


Cheers and have an amazing day!!

Add a Comment

Your email address will not be published. Required fields are marked *