C/C++ Comment Style

sundialsvcs · 02-25-2008, 11:05 PM

Quote:

Originally Posted by H_TeXMeX_H

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 omitted)

I like to put lots of comments in my code, but not so much as to explain the obvious, still enough to help you make sense of what I'm doing.

If you have not yet looked-up a copy of The Elements of Programming Style, either the original FORTRAN version or some later incarnation, "do so now."

Looking at your original block of comments (and dismissing the subsequent attempt at humor...) what I do not see is a practical attempt at added value.

"The code... I see." You do not need to add superfluous comments to this, because I see it as well as you do and I understand it as well as you did.

"What I need your comments to provide... is everything that I do not see from the code alone."

Human to human... you are talking to me. To a fellow human whom you've never met and whom you never will meet (umm, because you happen to be dead now). Don't tell me what I can already see from the code: tell me what's in your head right now. (Or I should say, what was. I can't dig you up right now. Yuck.) Gimme a nice trail of bread-crumbs.

jiml8 · 02-26-2008, 11:36 AM

I try to make my code as self-commenting as possible. To this end, I use descriptive variable names, descriptive define names, descriptive function names, and descriptive macro names. I also use an indent scheme that makes nesting as obvious as possible. Usually - not always - but usually, you can read right down my code and understand WHAT it is doing, even if you don't exactly know WHY.

For those cases where WHY is not obvious, I will use inline or block comments to try to clear that up.

I will use block comments ahead of functions that have switches and parameters passed in under all circumstances, and may use block comments ahead of functions whose purpose is not immediately obvious.

Shautieh · 02-26-2008, 02:05 PM

Quote:

Originally Posted by JMJ_coder

Box Comments

Code:

/*---------------------------------------------*/
/*                                             */
/* This is a comment box                       */
/*                                             */
/*---------------------------------------------*/

I don't use box comments as it's a pain in the ass each time you want to modify something

=>

Code:

/**
   Some big comments
*/

For the inline comments :

Quote:

Originally Posted by JMJ_coder

Code:

void SomeFunction (int *num1)
{// This is an inline comment to describe this function

   num1 = SomeCode();

}

^ I find this really ugly

Quote:

Originally Posted by JMJ_coder

Code:

// This is a single line comment to describe the following function

void SomeFunction (int *num1)
{
   num1 = SomeCode();
}

^ This is better, though the description of your functions should be written in your header file along with its declaration, not in the cpp one (but why not if you want to go into more in-depth details).

The best is to use doxygen style comments in your header anyway

dmail · 02-26-2008, 03:58 PM

As has been mentioned here I use comment syntax which is compatible with Doxygen. Some times this may be no comment at all as say a function or variable describes itself, yet at other times I use a Visual Studio plugin "Comment maker" which gives a uniform commenting pattern.

JMJ_coder · 03-18-2008, 02:02 PM

Hello,

I was looking at Doxygen and its syntax style for comments. I have a question - why does it but an extra star in the top line of the comment?

This:

Code:

/**
 * Some documentation
 * will go here!
 */

or:

Code:

/**
  * Some documentation
  * will go here!
  */

as opposed to:

Code:

/*
 * Some documentation
 * will go here!
 */

Why?

dmail · 03-18-2008, 02:51 PM

How ironic, you are creating docs yet can not read the docs for tool you are using.

Quote:

Special documentation blocks
A special documentation block is a C or C++ style comment block with some additional markings, so doxygen knows it is a piece of documentation that needs to end up in the generated documentation.

prad77 · 03-18-2008, 04:21 PM

Commenting is a good practice. I understood this not by practising, but by maintaining my fore-fathers code now. If not for the comments now , my grave will be preaching others to make comments.

So I made comments intendedly to be nice to others than to me. I prefer inline comments and block comments. Inline comments maketh the quick dry code walking easier. while block makes coding faster than spending time commenting elaboratley for every move made.

Fedora Development

chrism01 · 03-18-2008, 06:08 PM

For program headers & fn headers, I use open-ended box comments (nothing in the RHS) eg

#******************************************************************************
#
# Function : load_service_file
#
# Description : Open file for read, get recs, insert into DB, close file
#
# Params : $_[0] file to read
#
# Returns : none
#
#******************************************************************************
sub load_service_file
{
...
}

Actually, that's a Perl sub, but the same format applies. Open ended ones are easier to amend.

In commercial scale progs eg 1000's of lines of code, even well laid out code with proper
var names is still not as easy/quick to read as your native tongue.
I always assume the next guy/girl after me knows even less than I do about the lang and/or app and is under pressure to
produce an amendment/fix right now.(!)
This also applies to me some mths later, possibly with a hangover

Hence my comments do include the what as well as the why...

I also have as many lines of comment as needed inside the fn, using the multi-line style.

H_TeXMeX_H · 03-24-2008, 12:49 PM

I found some decent C/C++ style guides:
http://www.chris-lott.org/resources/cstyle/
http://www.computer-books.us/c_3.php

Not sure if they will help. I think style is developed through a lot of programming ... which I haven't done.

You know, I have to tell you, these days you're lucky if there's any comments at all, or they're usually in some language I can't understand ... like Russian. And those online translators don't work too well, although they got me through many of my French classes

The French teacher even complained to me once, said I used an online translator, but I managed to convince her that I didn't use one, because they produce mostly garbage. I was half right, I did use an online translator and then modified the result to make it understandable.

shambler · 04-01-2008, 10:14 PM

Quote:

What will "affect me" is the time that I waste trying to deduce the designer's intent.

This does it for me.

I also advocate doing that inside functions and methods. Code does not explain itself except in mechanical terms. Intent really is everything. If I want the mechanics, I'll read the code.
Splitting up a function into several smaller functions "so you don't need comments to explain what each function does" tends to obfuscate the overall intent because you've scattered common functionality in 3 or more places to meet an ideological goal. Not good.

You can tell somebody is either getting paid by the hour or has to meet some OCD company coding standard when you see stuff like this:

Code:

  i++;  // Add 1 to i

Doxygen as a system is pleasant for summary stuff. But it should not be the only method of commenting.

Another important thing is keeping the comments in sync with changes. Truism of the week: If the code and the comments disagree, both are probably wrong.

Or you could forget the whole comment and documentation hassle and just use the Front Ahead Design (FAD) paradigm. Ref:
http://thedailywtf.com/Articles/FrontAhead-Design.aspx

Dan04 · 04-01-2008, 10:48 PM

The style we're required to use at work looks like:

Code:

//------------------------------------------------------------
// example.cpp
//
//    Description of the file.
//
//    Copyright 2008 XYZ Computer Consulting.
//
//    VERSION   PROJECT#     DATE     DESCRIPTION OF CHANGE
//    -------   --------   --------   ---------------------
//     1.000     123456    04/01/08   Original creation.
//


//------------------------------------------------------------
// ExampleFunction
//
//    Description of what the function does.
//
//    Args:
//       nParam = description of the argument
//
//    Return:
//       int    = description of the return value
//
int ExampleFunction(int nParam)
{
   int nFoo;  // decription of the local variable

   //------------------------------------------------------------
   // Description of the code below.
   //
   nFoo = nParam * 42 + 17;
   return (nFoo);
}