Code Integrated Development Environment (IDE) such as Atom and VS Code has already provided a way to quickly format your codes nicely with just a few simple clicks or keyboard shortcuts.
The absence of comments by the people who wrote the codes in the first place would complicate the codes and in some cases, makes the code almost impossible to understand, even by the same people who code it in the first place.
You know how it is when your little pinky on your foot for smashed into a door or is accidentally stepped on, the pain, yes that pain. Multiply that by 1000 and imagine it in your brain. Yes, that’s how it feels like trying to understand codes without any context or comments.
There is a school of thought that believes commenting codes is redundant. This school of thought believes that if the method is too complex, it should be rewritten to be made simpler. No comment necessary. Also, for proprietary reasons, codes are left uncommented to ensure that if anything happens, the engineer who first built it will be called in to fix it. I do not subscribe to this school of thought. I believe codes should be commented on for a few reasons. Here are 10 of them:
1. Saves time
Time. Time is the only resource that is finite and you do not want to be stuck in front of a computer screen trying to find a solution to why this particular set of codes is not able to compile. By commenting on your code, it saves time by pointing out how the code works or let yourself or a future developer have some sort of description of what this code does.
In some cases, the time saved could be weeks and months of precious development allowance. As with many similar instances that any seasoned programmer can tell you, it is a daunting experience to dig through a code without knowing the heads or tails, where it starts, where it ends and how a particular function works.
2. Provide a pseudo-code to help you and, more importantly, your future self, understand what the heck is going on
There is a long-standing in-joke among programmers that once your code is done, only you and God knows what your code does. Six months later, only God knows what your code does.
By starting with a pseudo-code and leaving the pseudo-code in as a guide to help you build your app around, it does a lot in assisting you to get back into the mindset of why you write the functions and place it where it is supposed to be. See it as a breadcrumb trail for you or a future developer to understand what the heck is going on in this particular block of code.
3. Identify important blocks of code easily (and which code should not be tampered with under any circumstances)
Certain parts in your code just work and minor tamperings within that particular block of function might cause the whole program to, for a lack of a better description, implode or explode. Therefore, when it comes time to upgrade the code, putting a simple line of comment to a future developer or your future self might stop you from committing a grave mistake which might take months to undo.
By placing a certain warning on particular lines of code, any unwanted modification in the block of code to change its intent or purpose which might cause the whole program to break can be avoided.
4. Keep track of what needs to be done
By providing comments within your code, you can easily find the next tasks to be done within your software. Never get lost on what is happening and where you stop building your software ever again by commenting on what has been completed or otherwise.
It provides a naturally ordered process flow of the task that needs to be done within the source code itself.
5. Description and clarity of what certain blocks of code do by adding context
Certain block of codes requires extra explanation. Providing context concerning how this particular block of code works, it would provide a sense of clarity of why the code is the way it is.
Clarity and understanding of the purpose of a particular line of code are important to avoid unwanted confusion and (gasp!) deletion of certain blocks of codes.
Your future self or a future developer might get confused about why certain choices were made, hence…
6. “Why didn’t the programmer do it this way?” Here’s why…
When writing codes, certain methods are pretty obvious, but in some ways, certain method decisions are not obvious at first.
For example, why did you use division instead of multiplication? With comments, you can explain why this particular method was used for this particular block of code. When you revisit the code, it could in some way, make your future self or a future developer understand why this particular method works and the obvious method did not.
7. Comment out alternative methods that can be used
I sometimes comment out large pieces of code that act as an alternative method to the actual method that works, which is being used. By doing this, I can figure out and debug my code extensively by understanding which method worked and which method did not work.
Commenting out alternative methods can provide a way for you to go back to see what methods that have been tried and why it did not work.
8. Tag your codes in certain places so that you can come back to it
Maybe it's just me, but I usually place little snippets such as the word comment ‘elephant’ in my codes as a sort of bookmark for me to revisit this particular line in case I need to come back to it.
In certain places, I placed the words comment ‘tiger’, again as a bookmark, and to differ from the ‘elephant’ that I have commented on earlier.
Its also a reminder to myself, to come back to that particular line in case there was any problem in debugging the app in the future.
9. Let people know when the code was last updated
Back when I started to learn how to program, programmers needed to have a big ‘bunting’ at the top of their software (usually lines 0 to 10)to ‘announce’ the title of the software, the author of the software and when it was last updated. The prologue comments, as it is known, I have not seen this in source codes for, at least, the past 5 years.
With the advent of repositories, such as git and SVN, this art form has not been practised in a while. In my case, I have made it a habit to try to at least place the last updated date, hardcoded in a comment in the application that I wrote. Not necessarily having a formal prologue comment, but a date nonetheless.
While it probably does nothing, it could give a timeframe on when a particular set of code was last updated and by whom.
10. Let people know you are awesome
People who take their time to comment on their codes are angels. If you look at codes without any context for the first time, it would definitely take a while for you to understand what is going on.
But if you are an awesome developer and comment on your codes on what is going on, you sir/madam, are awesome. This is not a total exaggeration because understanding the code is important to move forward. By providing a guide, you are making the process simpler by providing a level of mindset and understanding of what is going through your mind when you write this particular line of code.
Comments do not affect the performance of any software at all. What comment does is it provides a way for you to understand, in human terms, what is going on within your code. To me, the positives outweigh the negatives in this case so guys and girls, let’s just start commenting on our codes.