Why writing comments are bad
Tags: webdev, programming, cleancode
Published: 2022-07-10 19:03:34

> 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.
<br/>
###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.
<br/>
###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.

{% embed https://gist.github.com/32db44f079af4f1fff25fd7c43bfd12e.git %}

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

    ```javascript
// 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:

    ```javascript
const birthdayHasAlreadyPassed = today > nextBirthday;
if (birthdayHasAlreadyPassed) {
      upcomingBday.setFullYear(today.getFullYear() + 1);
}
```
    Easy right?

3. Using another function

    ```javascript
// 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));
```
    &nbsp;
    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.

    ```javascript
      const hoursInADay = 24;
      const minutesInAnHour = 60;
      const secondsInAMinute = 60;
      const oneSecondInMilliseconds = 1000;
```
    &nbsp;
    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:

    ```javascript
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;
}
```

&nbsp;
###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.
<br/>
###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.
<br/>
###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.