Why you should put comments on code

We write unit tests so as to make sure our code functions as expected and we can get notified when there is a change in behaviour by the test-runner

We should write comments so that a developer can reassure his understanding of code by reading comments

Thus it can also be considered as a unit test for developer.

More so if you are not immediately writing unit tests for code, in future either you or your peer can take comments as a guideline to write unit tests

Every person has an intrinsic test-runner in mind which keeps testing things

When you write relevant comments, the test runner in the mind of the developer can help release endorphins for the developer

So even if code is self-explanatory, you should write comments

Some say —

Code is like a joke, if you have to explain it through comments, it’s not good enough

While extreme intelligentsia might be able to play around with code as a joke, for masses it’s still a serious business so we should explain it such that masses can derive serotonin boost reading the comments

Proper use of commenting can make code maintenance much easier, as well as help find bugs faster. Remember, well-documented code is as important as correctly working code.

Where to Comment:

Comments should occur in the following places:

The top of any program file.

  • This is called the “Header Comment”. It should include all the defining information about who wrote the code, and why, and when, and what it should do

Above every function.

  1. This is called the function header and provides information about the purpose of this “sub-component” of the program.
  2. When and if there is only one function in a file, the function header and file header comments should be merged into a single comment. (See Function Header below)


  1. Any “tricky” code where it is not immediately obvious what you are trying to accomplish, should have comments right above it or on the same line with it.

Well, Thank you if read through this!




I love learning

Love podcasts or audiobooks? Learn on the go with our new app.

Recommended from Medium

Create a Serverless App on AWS using TypeScript

Improving Flutter with your opinion — Q4 2019 survey results

Hi Quackers!

Quorum x Capture The Talent: Friends Writeup

When Studying Web Development, Patience is a Virtue

Manufacturing Execution Systems: 8 top Solutions

How to get a fully automated API lifecycle with Azure API Management

Guide to rock solid, bug free, quality software.

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
Akshay Jain

Akshay Jain

I love learning

More from Medium

You don’t need more developers

I’m no longer motivated at work.

A man stares dumbfounded at a laptop

These Ninjas don’t write pseudo code anymore!

My developer’s journey