When you should comment your code?
Commenting vs documenting and when to comment
Davi Mello
Commenting vs Documenting
Commenting is a translation between two languages that developers know, aiming to ease the understanding of a behavior.
Documenting is different, it is about requirements and modularity, and it is (almost) always good to have, especially when dealing with teams. The general fear of over-documentation is so rare that it became a myth. Patterns like JSDoc are ways of documenting your code, not commenting.
For example, this is a documentation:
/**
* Get the content from ID.
* @param {Object} event The event object.
* @param {Object} body The body of the request.
* @returns {Promise}
* @see {@link module:services/content/catalog}
*/
function getStuff(event, body){
//...
}
This is a comment:
// If the objects are the same, throw error 542
JSON.stringify(obj) === JSON.stringify(obj2) && throw new SystemError({ code: 542 })
So, when to comment?
When a verbose version of your code is not enough to describe its behavior. When understanding it in plain-English is significantly faster than in code.
Why?
Programming is like writing a text: The comprehension is subjective. It may vary due to numerous factors: region, subject, epoch, cultural factors. The understanding about the code may vary between new developers and old-school developers, between a REST developer and an Event Driven, between people who had a CS/engineering courses and those who don't.
Other developers will consume your comment before they consume the code, so it can speed up things up. If I need to refactor a code and your complicated line is not the place that I need to take a look, I will skip it.
But why this is important at all?
Speed.
Gifted minds commonly dislike commenting and documenting due to the fast way that they think. They are very productive - when assigning the sheer number of complex features that they can pull in a short time - but they struggle to scale when working with other developers. This can even be a major problem, since they feel that they are not being productive when slowing down to assist others.
If you want to know how extremely genius people write insane on-liners to abstract a whole component, you can join CodeSignal, enroll on any code challenge and take a look into the top answers. A code-base created like that and without comments or documentation will be simply unmaintainable.
Upvote
Davi Mello
I am a person

Related Articles