Code also has emotions. Let's comment only when required.

4 min readJan 4, 2022

Writing comments to a code is a very good practice but it can be avoided at times when it is actually not required. A good code is always self explanatory.

I am actually very afraid when it comes to fixing some bug in a code that is not written by me. It becomes very difficult for me to understand the piece of code obviously because it's not written by me.

But a few days back I came across a codebase where the code was very readable and I was able to fix the bug very quickly. The code was quite admirable. Very few comments but the code was self-explanatory Coding is a beautiful thing if you see. Being a developer means we have to read code, write code or make changes in an existing code. If we do not understand a code it becomes very uneasy as it decreases our effectiveness and productivity. Let's make some rituals while you read this post and follow it for the best results.

Talking about my experience the worst thing I have experienced is code that is commented out. I mean why do we want to comment out code instead of removing it?

We all use version control for our code to track the changes or the edits that are made. Still, we comment on the code instead of removing it. Let's trust in the version control and make our code look as clean as possible.

Imagine a code like this :

if( sunRisen) {
 // washClothes();
 // dryClothes(); 
 // wrapClothers();
 manageClothes();
 } else { 
donothing();
 }

Why do we need the commented code when it is of no use. It is just a wastage of line and code size.

Ritual 1:

Let's make a ritual to delete the code not required and not comment it out before committing our code.

if( sunRisen) { manageClothes(); } else { donothing(); }

This looks much better.

Ritual 2:

Let's make a ritual to add prefix //FIXME or //TODO to our comment so that it is taken special care of.

There are some times where we have to annotate a problem or annotate a solution. Side by side it is great if a ticket is created for these as well.

createBreakfast(config) { 
// TODO: need to pass an optional param for type of salt (white or pink) 
const foodPrepared = return startCooking(config);
return foodPrepared;
 }

Ritual 3:

Let's make a ritual to not write comments for code if the code is already understandable.

// to check if warning modal should be shown or not shouldShowWarningModal(){ 
return !this.isModalSeen && !this.isValidUser;
 }

The comment here is useless because the function name itself is self-explanatory. Self-documented and self-explained code is magic. Choose the functions name and variables name wisely.

Ritual 4:

Let's make a ritual to explain our code only when required and that too possible in the least number of words. Note: Start comment with a whitespace to make it more readable. For more read: spaced-comment

function getName() { 
// set the default name to 'no name'
 const name = this.name || 'no name'; 
 return name;
 }

Ritual 5:

Let's make a ritual to follow the standard practice so that one day when someone reads our code they understand it easily. It is always easy to point mistakes in other people's code but it is very difficult to follow good practices ourselves.

Ending on a positive note as it is a personal choice to write or not write comments. My motive was to say that code also has emotions and feelings. Let's help the code to portray its emotions and not always comment on them. :)

Originally published at https://www.simranraj.in.

Code also has emotions. Let's comment only when required.

Written by SIMRAN RAJ