Why writing comments are bad

To write comments or Not to write comments, that is the question

Without doubt, this is one of the most controversial topics among developers. Some believe that writing comments should be the last option, and others think comments can be use freely. As you might have guessed I am personally against writing comments to describe code and here are some of the reasons I can mention why.

Ok at first, Outdated after a while

If you write a code that doesn't work, unit tests will fail or your editor (aka compiler) will complain. However, there is no mechanism to check your comments. Let's say after one year of writing a comment for a function, you or other developer change the functionality of that function without paying attention to change the comment accordingly specially because there is no unit test to check if your comment still describes what your code does. Eventually, this will be the cause of so many obsolete comments in the project. This mostly happens because most of developers don't bother to even read comments.

Good code doesn't need comments

If your code clearly describes the purpose of the code then why would you need comments in the first place? If you are able to write clear, readable code accompanied by readable tests, no comment will be able to beat that.
As an example, here is a code which uses comments to describe some parts of the code and we'll see if we can eliminate the need for them.

Well, I can thing of 3 things here:

1. Change the function name

   As we can see the function name doesn't say much, so if we use a more descriptive name instead of just a word, it would certainly eliminates the need for the first comment. My suggestions would be getRemainingDaysToBirthday or calculateRemainingDaysToBirthday.

2. Use descriptive condition
   

   // if birthday has already passed, set next year as birthday
   if (today > upcomingBday) {
     upcomingBday.setFullYear(today.getFullYear() + 1);
   }
   

   Here we can describe condition inside the code without using comments:
   

   const birthdayHasAlreadyPassed = today > nextBirthday;
   if (birthdayHasAlreadyPassed) {
     upcomingBday.setFullYear(today.getFullYear() + 1);
   }
   

   Easy right?

3. Using another function
   

   // getTime() returns in milliseconds so we divide the result in milliseconds to get number of days
   const result = Math.ceil((upcomingBday.getTime() - today.getTime()) / (24 * 60 * 60 * 1000));
   

    
   First of all whoever reads this code probably wouldn't understand what 24 * 60 * 60 * 1000 does specially what the 1000. Instead, we can use descriptive constants to describe each what each digit represents.
   

     const hoursInADay = 24;
     const minutesInAnHour = 60;
     const secondsInAMinute = 60;
     const oneSecondInMilliseconds = 1000;
   

    
   But how about the first part? Well we can use functions to increase readability, and in this case, describe what this piece of code does:
   

   function getDaysToBirthday(nextBirthday, today) {
     const hoursInADay = 24;
     const minutesInAnHour = 60;
     const secondsInAMinute = 60;
     const oneMillisecond = 1000;
     const OneDayInMilliseconds = hoursInADay * minutesInAnHour * secondsInAMinute * oneMillisecond;
   
     const daysToBirthday = Math.ceil(nextBirthday.getTime() - today.getTime() / OneDayInMilliseconds);
   
     return daysToBirthday;
   }
   

 

Makes you a bad developer

You can always describe what you are doing in comments so why bother to write a clean code? It always takes some effort and time to write a cleaner code without needing a comment so by having restrict rules about them, everyone in the team will force to write a code which describe itself.

So should I avoid comments at all costs?

I don't think you can find anyone who says "never" to comments, however, in general you should always avoid writing comments as much as possible by writing clean, readable code which explain itself accompanied by good tests. this will certainly eliminates the need for comments.
However, there are some cases which they could be useful such as using comments to document APIs or describing complex operations which is impossible the team tried their best to write a good code but still needs comments to clarify what the operations does or why this code exist.

Disclaimer

I am pretty sure there are so many good developers out there who can complete this list or they have other opinions. Please let me know what you think in the comment section below it means so much to me and help me grow my knowledge. I appreciate in advance.

Comments

[Alex]

My main concern with "splitting" out your code to be more "readable" is that, for the most part, you're adding uncessesary compute time/steps. Comments do not impact the performance of your code whilst providing a clear outline of what the code does, for whomever it may concern.

Just my opinion at the end of the day, guess I'm just a stickler for efficient code. Perhaps someone will agree with me 😁

[Mo Ghanbari]

IMO the bad performance issue that you are talking about is extremely tiny versus the important areas you can cover like readable code, less bugs and ... .
Also minified files generated by compilers will make this problem even less important.(not 100% sure about this though).

At the end I found this comment in the following article helpful. Take a look: How important is it to reduce the number of lines in code?

Thanks Acol, also doesn't mean I'm 100% correct. Very controversial topic 😜✌️