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)

Inline

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!