Are there standard formats for comments within code? [closed]

Answer 1

The problem with comments within a method (rather than in an interface), is that they are actually not meant to be seen by anyone except for people maintaining that method. Therefore, there is no real need for a standard for the comments. They don't get published anywhere, they're not publicly visible, callers will generally never see them.

In general, comments inside code should follow four rules:

1. They should not state the obvious
2. They should be consistent with what they describe
3. It should be clear what they describe (e.g., which line, block).
4. They should be readable by any future maintainer.

That being said, there is often a tendency to place information that is important to the callers as an internal comment. For example: "OOPS, This doesn't handle negative numbers". Whenever you see an internal comment, reconsider whether the header documentation should be updated, or use a tool that "pushes" the comments to the awareness of function callers (I have a tool like that for Java).

Answer 2

Comments standards are most useful when the comment will be parsed by an external tool (usualy, a document generator, like javadoc).

In this case, the external tool will state the standards.

For other cases, see How do you like your comments? (Best Practices)

Answer 3

' I usually write comments like this