How to Make Program Comments More Useful?

Question

Hai guys,

I ve seen people including comments in their program..

• Is it to improve inter-programmer communication and code readability, by explicitly specifying programmers’ intentions and assumptions?

• Should comments be in technical terms rather than in natural launguage terms?

• How to use comments as effective as possible?

• Is it really a good practice adding comments to a program?

Answer 1

Comments can be used for auto-documentation, communication amongst other developers, memory, todo lists, or basic explanations of functionality. Note that comments ought to be supplementary - if your code needs comments, you need to reconsider your code.

To be as effective as possible, work out a template for your comments to exist in. Again, this will not only help you read and understand your code, but it may help a parser create documentation for you from your comments if they're in a consistent format throughout the code.

Answer 2

Comments should only be used to explain why the code is the way it is. It should never explain what the code is doing. What the code is doing is described by the code.

That being said, some languages have tools that look for special characters in the comments in order to generate documentation. Java is one such language. But these aren't so much code comments as they are documentation that happens to use the same syntax as language comments.

Answer 3

I try and comment each function describing at a high level, but precise way, what the function does. The precision should be such that it is not necessary to read the body of the function to understand what the function does, or to re-implement it and have it work perfectly with any code that calls it.

Other than that, I try and keep functions small enough that the above is basically all the necessary documentation.

Once in a while, there may be something obscure or odd in what is being done in the code - I document that. Anything that isn't obvious or intuitively right, or that you spent some time thinking about, should be documented.

Just imagine you have a memory problem and will forget writing this program in a month. Then imagine you have to go back and fix it. What would you like commented and how could those comments be made most useful to you?

Answer 4

First try to write code so people can follow without comments.

Answer 5

it's better to make the program self-describing, then no much comments are needed.

Answer 6

Writing clear code is always the first step to making your code easy to understand. You can then explain parts that are not clear by looking at the code, in comments.

For myself, comments explain what I was thinking at the time. That way, six months from now when I don't remember what I was writing, I can use the comments to understand.

Some classic uses of comments:

• Explaining why code wasn't done in the most obvious way -- Such as interfacing with systems that use weird or old ways to talk.
• Explaining what code might call this code -- Such as in large and complicated system. You can add examples showing code that might need to call this.
• Documenting exceptions to current coding practice -- Such as legacy code that hasn't been refactored to use the current systems.

As a rule, if you ever find yourself doing something non-obvious, comment it.

An alternative way of commenting is to start by writing the body of a function as comments. Then break the comments apart and put the code underneath. When it finally works, cleanup and fix the comments.

Ciao!