How to write a good comment? Any suggestion!

Question

Related to comment in programming languages.

Answer 1

For files containing package or class:
Comment header with creation date, authors, description of general functionality of package/class. Some people put list of changes and its dates but I think it's better put that in control version comments.
Functions :
Description of functionality, required parameters and output result.
Some people includes pre/post conditions that in/out parameters must fulfill.

General rule: It is better using meaningful names of functions/classes/variables than filling code with redundant comments.
Put comments in code hard to understand, work-arounds, use of third party obscure APIs, etc...

Answer 2

Depends on what you’re commenting on really. Comments inside your code should be used when something needs an explanation, usually a good practice is to comment more complicated blocks. Functions and Methods can also be commented to explain what it does, what it accepts and what they return.

There is of course differences of opinion on this topic, some argue that code should be self commenting by writing code with strong type-hinting and some prefer a lot of comments.

Usually it depends on where you work. If you want a fuller answer I’d check out a coding style guide and adopt some of that.

Answer 3

Here is a style guide for comments, it uses a pretty widely adopted way of doing it.

https://github.com/airbnb/javascript/blob/master/README.md#

It’s for JavaScript, but you can always find one for a different language as well. A lot of IDEs support the above example and create some nifty color schemes to make your comments stick out more.

Hope it helped.