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!

I love learning

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

Recommended from Medium

Using XIB-Connected View Controller as Entry Point in iOS 13 Project

What is Amazon S3? How to host your react website with Amazon S3?

The Hidden face of Google Caching

Robotic Process Automation — What is it, and why do we need it?

Spring Batch — Multithreaded Steps

The Journal App Making Journal: Day 45

Introducing HbarX: First Staking Solution for Hbar Token Users

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

Software happiness

3 Things I Should Have Done as a Software Engineer

Process is Easy; People are Hard

Office work vs remote work — which one is better for you?