10 reasons why you should place comments in your code

Feb 15 · 7 min read
Photo by Luca Bravo on Unsplash

Actual. Human. Readable. Comments. Whether you are writing codes in PHP, JavaScript, TypeScript, Java, C, C#, Rust, Python and many other multitudes of computer language, many seemed to have forgotten (or leave out completely) the art of commenting on your code.

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:

Photo by Lukas Blazek on Unsplash

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.

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.

It works like magic!

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.

Photo by Kaleidico on Unsplash

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.

Photo by Markus Spiske on Unsplash

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…

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.

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.

Photo by James Hammond on Unsplash

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.

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.

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.

Selamat Mengaturcara

The Startup

Get smarter at building your thing. Join The Startup’s +787K followers.

Thanks to Trey Huffine

Sign up for Top 10 Stories

By The Startup

Get smarter at building your thing. Subscribe to receive The Startup's top 10 most read stories — delivered straight into your inbox, once a week. Take a look.

By signing up, you will create a Medium account if you don’t already have one. Review our Privacy Policy for more information about our privacy practices.

Check your inbox
Medium sent you an email at to complete your subscription.


Written by


Husband, son, father & multi award winning app developer. 😊❤️ TypeScript and JavaScript. Proud to be Malaysian. Sometimes I tweet @razmans

The Startup

Get smarter at building your thing. Follow to join The Startup’s +8 million monthly readers & +787K followers.


Written by


Husband, son, father & multi award winning app developer. 😊❤️ TypeScript and JavaScript. Proud to be Malaysian. Sometimes I tweet @razmans

The Startup

Get smarter at building your thing. Follow to join The Startup’s +8 million monthly readers & +787K followers.

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store