Thread: comments

It depends. Here's an example

Code:

...
/* Attributes of Cats */
char name[8]; /* Name of the Cat */
int age; /* Age of cat*/
int weight; /* Weight of Cat */
...

[EDIT: I wrote the example too fast and forgot the semicolons]

The most important thing is to write decent comments.

Things like "variable declaration" and "name of cat" are not the type of thing you want to be commenting. This is simply because anyone with half a clue about C will know that a char array called "name" is an array for holding a name!

Document why your code does things, and if complexity requires it, document the how. Don't document the blindingly obvious.

>>It's different, how to comment your code
you have to find your own way....<<
Not when you're working in a team. A common understanding/style is a better approach, imo.

My style also varies some, but in general:

A block comment before a block of code explaining what's about to happen, probably multiline comment

A post-line comment to explain what this line does or what the variable is for
int tramp; /* counts the number of hobos to date */

Post-line comments also at the end of if/for/while/switch structures

Code:

        }  // end of if (a != 7)
    }      // end of for lp2
}          // end of if !done

I will also mix /* */ and // in a program -- I'm not that much of a purist

oops, forgot the close code. at least I remembered the opening tag!

Don't comment things that can be easily understood from the code. Remember, documentation has to be kept synchronized with the code itself. If code is clear, but the comments are out of date, then the programmer doing maintenance has to figure out if the comment is in fact out of date, or if the code is actually doing something more than meets the eye, and wastes time on that. Of course, if your code does do something more than meets the eye, it should be commented.

I indent my code like this

Code:

int main()
{
     char a,b,c,d;
     return 0;
}

I think that most people find it a lot easier to read than those "other" ways.

Comment as needed. When you're learning, you might want to comment stuff that you'd never consider commenting later. Just comment whatever you think might confuse you.

I always use // instead of /* */ comments just because I find it looks better. Although it is a pain to have to take out twenty //'s when you would have just had to take out the /* */'s. :P