CODEWITHSUNDEEP
comments
ACP
ACP

Reputation: 35268

How to Make Program Comments More Useful?

Hai guys,

I ve seen people including comments in their program..

Upvotes: 2

Views: 345

Answers (6)

docwhat
docwhat

Reputation: 11704

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!

Upvotes: 2

Benny
Benny

Reputation: 8815

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

Upvotes: 1

fastcodejava
fastcodejava

Reputation: 41097

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

Upvotes: 0

Sampson
Sampson

Reputation: 268374

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.

Upvotes: 2

Larry Watanabe
Larry Watanabe

Reputation: 10184

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?

Upvotes: 1

Bryan Oakley
Bryan Oakley

Reputation: 386030

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.

Upvotes: 7

Related Questions