C/C++ Comment Style
Hello,
For all the C/C++ programmers out there: What is your favorite comment style for your source code (C programmers, ignore all the //'s ;)) Box Comments Code:
/*---------------------------------------------*/ Code:
void SomeFunction (int *num1) Code:
// This is a single line comment to describe the following function Code:
/* This is a single line comment to describe the following function */ Vertical Column Comments Code:
/* Code:
/* Also, how much do you comment your source code? Does every inane thing have a comment (i.e., this is the #include section, this defines functions SomeFunction1() and SomeFunction2())? |
I'm trying to figure this stuff out too. Usually I use C++ style comments for regular comments and the C style comments to comment out large sections of code (including possible C++ comments), which would not be possible if I used C style comments for everything.
Here's a sample program I wrote a couple days ago just for fun, don't expect it to be perfect or a good idea, I'm not an expert C programmer. Code:
// generate random numbers using /dev/urandom And, yes probably for the header it's better to do something fancy like: Code:
/**********************************************************/ |
Quote:
Anyway, I comment mostly with single-line comments prior to important functions and prior to or on the same line as statements with non-obvious results. On some projects I place column-style comments prior to a function, describing all inputs and outputs. I don’t use any fancy box styles, although the boxes program allows you to create them in editors like vi. My favorite of their examples is the peek style. Btw, you completely forgot preprocessor comments. These aren’t really comments at all per se (they’re not supposed tell you anything about the code), but they allow one to “comment out” large sections of code and make it easy to “uncomment” quickly. Another benefit here is you can put them around normal (multi-line) comments without worrying. This is most useful when you have a function which you want to replace or get rid of. For example, Code:
#if 0 |
Well, I comment ALL functions (/methods), usually using doxygen (or Javadoc) style comments.
Code:
/** Code:
/* Nasty old, ugly way of doing that |
Box comments are painful to maintain, so I avoid them. I normally don't even use /**/ comments unless I have a paragraph to write. I generally comment between a function name or conditional and its {} with the purpose of the function or condition, but only if it's significant and then only one line. If there's something that I know I as the maintainer will wonder about later, I use a //NOTE:. I rarely use a multi-line comment unless it's in an API header. Sometimes I'll block off a class or function like this:
Code:
//Class my_class-------------------------------------------- ta0kira |
Comments are most useful if they're short, in plain english, and accurate. That way they're more likely to be updated as the program gets modified.
In other words, pay more attention to what you put in them than how they look. |
Quote:
ta0kira |
Quote:
|
Quote:
Two additional notes: 1. Comments should always be "at the level of intent" <= "What" you're doing should be obvious from the code So the comment should (briefly!) explain the "why" In other words: what is the *goal* of this block of code? 2. Although it's not so much important how comments look... ... it *is* important to be *consistent* in how they look. This is the reason for coding standards - to insure consistency. |
There needs to be some sort of auto-commenting IDE plug-in where you select a function name and it lets you fill in a few fields, then it adds or edits the comments based on your own style. Also, something like OpenOffice styles where you can change the master style definition and it will update it everywhere.
ta0kira |
Quote:
Moreover, one never knows who is going to maintain a piece of code in the future in these foreign outsourcing times ... |
Hello,
Quote:
|
Hello,
Quote:
|
Quote:
As for all other comments... I typically only put comments in the header files (with my class definitions or function prototypes) and I use the Doxygen format so I can easily create decent developer documentation. |
My "comment style?"
Easy. "Clear." Honestly, I really don't care how you prefer to do it. Over the years I've read and worked-with code that runs the full gamut of programmer personal-preferences. I do prefer that you "pick a style and stick with it," but I frankly don't care too much what that style might be. Stylistic peculiarities will not affect me. What will "affect me" is the time that I waste trying to deduce the designer's intent. Quote:
|
All times are GMT -5. The time now is 05:57 PM. |