Commenting style?

[Angel Tsankov]

Can someone recommend a good source of C/C++ coding style.
Specifically, I am interested in commenting style and in
particular how to indent comments and the commented code, rather
than when to use comments. Thanks in advance!

 

[Satish]

Basically attached is the class layout and source code layout... You
can see the comments section. Also if you want to comment a large
piece of code but at the same time you don't want to delete the code
use #ifdef like

#ifdef JUST_FOR_COMMENTING_OUT
code here which you dont want to execute
#endif

Hope this helps!

Satish

##############CLASS LAYOUT##########################
/**
* A one line description of the class.
*
* #include "XX.h" <BR>
* -llib
*
* A longer description.
*
* @see something
*/

#ifndef XX_h
#define XX_h

// SYSTEM INCLUDES
//

// PROJECT INCLUDES
//

// LOCAL INCLUDES
//

// FORWARD REFERENCES
//

class XX
{
public:
// LIFECYCLE

/**
* Default constructor.
*/
XX(void);

/**
* Copy constructor.
*
* @param from The value to copy to this object.
*/
XX(const XX& from);

/**
* Destructor.
*/
~XX(void);

// OPERATORS

/**
* Assignment operator.
*
* @param from THe value to assign to this object.
*
* @return A reference to this object.
*/
XX& operator=(XX& from);

// OPERATIONS
// ACCESS
// INQUIRY

protected:
private:
};

// EXTERNAL REFERENCES
//

#endif // _XX_h_

APPENDIX B - Source File Code Layout


#include "XX.h" // class implemented

/////////////////////////////// PUBLIC
///////////////////////////////////////

//============================= LIFECYCLE
====================================

XX::XX()
{
}// XX

XX::XX(const XX&)
{
}// XX

XX::~XX()
{
}// ~XX

//============================= OPERATORS
====================================

XX&
XX:perator=(XX&);
{
return *this;

}// =

//============================= OPERATIONS
===================================
//============================= ACESS
===================================
//============================= INQUIRY
===================================
/////////////////////////////// PROTECTED
///////////////////////////////////

/////////////////////////////// PRIVATE
///////////////////////////////////

 

[mlimber]

[cross-posting deleted]

Basically attached is the class layout and source code layout... You
can see the comments section. Also if you want to comment a large
piece of code but at the same time you don't want to delete the code
use #ifdef like

#ifdef JUST_FOR_COMMENTING_OUT
code here which you dont want to execute
#endif

Hope this helps!

Satish

##############CLASS LAYOUT##########################
/**
* A one line description of the class.
*
* #include "XX.h" <BR>
* -llib
*
* A longer description.
*
* @see something
*/

#ifndef XX_h
#define XX_h

// SYSTEM INCLUDES
//

// PROJECT INCLUDES
//

// LOCAL INCLUDES
//

// FORWARD REFERENCES
//

class XX
{
public:
// LIFECYCLE

/**
* Default constructor.
*/
XX(void);

/**
* Copy constructor.
*
* @param from The value to copy to this object.
*/
XX(const XX& from);

/**
* Destructor.
*/
~XX(void);

// OPERATORS

/**
* Assignment operator.
*
* @param from THe value to assign to this object.
*
* @return A reference to this object.
*/
XX& operator=(XX& from);

// OPERATIONS
// ACCESS
// INQUIRY

protected:
private:
};

// EXTERNAL REFERENCES
//

#endif // _XX_h_

APPENDIX B - Source File Code Layout


#include "XX.h" // class implemented

/////////////////////////////// PUBLIC
///////////////////////////////////////

//============================= LIFECYCLE
====================================

XX::XX()
{
}// XX

XX::XX(const XX&)
{
}// XX

XX::~XX()
{
}// ~XX

//============================= OPERATORS
====================================

XX&
XX:perator=(XX&);
{
return *this;

}// =

//============================= OPERATIONS
===================================
//============================= ACESS
===================================
//============================= INQUIRY
===================================
/////////////////////////////// PROTECTED
///////////////////////////////////

/////////////////////////////// PRIVATE
///////////////////////////////////

Satish, please don't top-post here (see
http://www.parashift.com/c++-faq-lite/how-to-post.html#faq-5.4).
Second, formatting style is largely a matter of preference. The OP can
find some guidelines and links in the FAQ
(http://www.parashift.com/c++-faq-lite/coding-standards.html) and can
google for more, but the most important thing with formatting is
consistency.

On a personal note, I prefer not to use the preprocessor to "comment
out" code like Satish does above. Instead I use // comments throughout
and use /**/ comments to get rid of blocks and/or regular expression
search-and-replace to add // to the beginning of each line I want to
comment out.

Cheers! --M

 

[Alf P. Steinbach]

* mlimber:

On a personal note, I prefer not to use the preprocessor to "comment
out" code like Satish does above. Instead I use // comments throughout
and use /**/ comments to get rid of blocks and/or regular expression
search-and-replace to add // to the beginning of each line I want to
comment out.

Agreed that // comments are less visually imposing. And it's a shame
that /*...*/ don't nest, necessitating using condititional compilation
as a commenting-out device. However, the main problem with the example
shown in Satish's posting -- which by the way seems to be geared
towards some documentation generator -- is the attempt at classifying
class members; in practice such fixed classifications very seldom, if
ever, correspond to any natural division nor a natural layout of the
code. Just in now: I see that Satish is multi-posting the same example
to comp.lang.c++.moderated. Perhaps discussion of that example is
better moved there...

It would be nice if the C++ preprocessor had a #region directive like
C#, in order to create logical groups (collapsible in smart editors).

But it doesn't.

 

[=?ISO-8859-15?Q?Juli=E1n?= Albo]

It would be nice if the C++ preprocessor had a #region directive like
C#, in order to create logical groups (collapsible in smart editors).
But it doesn't.

A #pragma can do the job. Or a difficult to write by accident sequence or
characters put in a comment, as automatic documenting tools do. There is no
need of direct support in the language for that type of things, just an
agreement between editors, or plug-ins for editors, writers.

 

[Noah Roberts]

Can someone recommend a good source of C/C++ coding style.
Specifically, I am interested in commenting style and in
particular how to indent comments and the commented code, rather
than when to use comments. Thanks in advance!

That's very subjective that can depend on team standards or possibly
document generation programs (like doxygen). The best book on C++
standard I have ever read, C++ Coding Standards, says, "Don't sweat the
small stuff." I would qualify what you're asking as such. You're
going to get as many different answers as there are people on the
planet....that code in C++.

My personal preference is to follow the smells theory in which code
commenting is a smell:

http://www.awprofessional.com/articles/article.asp?p=102271&seqNum=2&rl=1

I do provide comments in my headers to document my classes though.
These are in the form of doxygen comments and are meant for automated
documentation generation, not necissarily the code maintainer. As such
I stick to the standards imposed by that program.

 

[Rolf Magnus]

* mlimber:

Agreed that // comments are less visually imposing.

Well, for a single line, they are. More importantly, they are less to type.
I only use the /* */ comments for... well, comments. My editor also
highlights comments differently from #if 0 #endif blocks, so that I can
immediately see what is comment and what is deactivated code.
The // ones I use to quickly deactivate a single line of code when
experimenting.

And it's a shame that /*...*/ don't nest, necessitating using
condititional compilation as a commenting-out device.

Why? It's more natural IMHO to use that instead of comments. After all,
things like that are the preprocessor's main job in C++.

However, the main problem with the example shown in Satish's posting --
which by the way seems to be geared towards some documentation
generator

Seems to me, too. Reminds me of Doxygen. However, there is nothing wrong
with writing comments in a style compatible with that, even if you don't
use it.

It would be nice if the C++ preprocessor had a #region directive like
C#, in order to create logical groups (collapsible in smart editors).

I don't see why this should be part of the preprocessor.

 

[Alf P. Steinbach]

* Rolf Magnus:

Well, for a single line, they are. More importantly, they are less to type.
I only use the /* */ comments for... well, comments. My editor also
highlights comments differently from #if 0 #endif blocks, so that I can
immediately see what is comment and what is deactivated code.
The // ones I use to quickly deactivate a single line of code when
experimenting.


Why? It's more natural IMHO to use that instead of comments. After all,
things like that are the preprocessor's main job in C++.

On second thoughts, it may be you're right. It just feels wrong to use
more than one convention for commenting out code (conditional
compilation can't be used within lines without reformatting), +, it
tends to leave "#if 1" and some later "#endif" or similar mystifying
things in the code, "just in case I need to examine this again".

I don't see why this should be part of the preprocessor.

It's practical.

Having umpteen different conventions, with varying or no tool support,
is IMO not.

 

[BobR]

Alf P. Steinbach wrote in message ...

* Rolf Magnus:

On second thoughts, it may be you're right. It just feels wrong to use
more than one convention for commenting out code (conditional
compilation can't be used within lines without reformatting), +, it
tends to leave "#if 1" and some later "#endif" or similar mystifying
things in the code, "just in case I need to examine this again".

Having umpteen different conventions, with varying or no tool support,
is IMO not.

#if 0
- invalid stuff here -
#endif

I was shocked when the compile stopped with error.

/*
- invalid stuff here -
*/

No problem.

But, I'm sure it depends on the compiler used. <G>

 

[Ian Collins]

/**
* Default constructor.
*/
XX(void);

/**
* Copy constructor.
*
* @param from The value to copy to this object.
*/
XX(const XX& from);

/**
* Destructor.
*/
~XX(void);

A classic case of superfluous comments if ever a read one. The use of
(void) is also unnecessary and bad style in C++.

 

[Angel Tsankov]

Second, formatting style is largely a matter of preference. The

OP can
find some guidelines and links in the FAQ
(http://www.parashift.com/c++-faq-lite/coding-standards.html)
and can
google for more, but the most important thing with formatting
is
consistency.

Thanks a lot for this reference!

 

[Angel Tsankov]

On a personal note, I prefer not to use the preprocessor to

Agreed that // comments are less visually imposing. And it's a
shame that /*...*/ don't nest, necessitating using
condititional compilation as a commenting-out device. However,
the main problem with the example shown in Satish's posting --
which by the way seems to be geared towards some documentation
generator -- is the attempt at classifying class members; in
practice such fixed classifications very seldom, if ever,
correspond to any natural division nor a natural layout of the
code.

This seems a good point! And one more this: should one use
different styles to comment a function and a couple of lines
inside that function, e.g.:

///////////////
// Function description
///////////////

void f( )
{
// NOTE: There is a caveat in the following lines of code
...
// Here come more lines that do not have any caveats. How
should one make that clear? Should they be separated by a couple
of empty lines or what?
}

 

[Rolf Magnus]

* Rolf Magnus:

On second thoughts, it may be you're right. It just feels wrong to use
more than one convention for commenting out code (conditional
compilation can't be used within lines without reformatting),

Yes, that's true. I tend to use comments for unused parameter names to avoid
compiler warnings, like:

void Someclass::myfunc(int /*param*/)
{
// param not used in this function
}

#if 0 / #endif wouldn't be too convenient here.

+, it tends to leave "#if 1" and some later "#endif" or similar mystifying
things in the code, "just in case I need to examine this again".

Well, if you use comments, that would leave /**/ and some later again /**/
in for the same reason. In that case, you wouldn't even see which was the
start and which was the end, unless you explicitly add that information to
the comment.

It's practical.

Having umpteen different conventions, with varying or no tool support,
is IMO not.

IMHO, something like that should not be part of the language.

 

[=?iso-8859-1?q?Erik_Wikstr=F6m?=]

different styles to comment a function and a couple of lines
inside that function, e.g.:

///////////////
// Function description
///////////////

void f( )
{
// NOTE: There is a caveat in the following lines of code
...
// Here come more lines that do not have any caveats. How
should one make that clear? Should they be separated by a couple
of empty lines or what?

}

Yes, that's the way I usually do things, group a couple of lines that
belong together by surrounding them with blank lines, often I also add
a comment above the code describing what they do (less than 5 words
usually do). If some part is particularly complicated I use a longer
comment. If the whole operation of the function is complicated then the
information about that goes above the function.

I usually comment each method in the .h-file in a way that tells a user
of the class/function what it does and which parameters are what etc.
and then, if the method is non-trivial I add additional comment
describing how it works in the .cpp-file. So, comments for users in
..h-file and comments for maintainers in .cpp-file. Exactly how you
format the comments are seldom of importance as long as they are
informative and correct (unless it's for automatic documentation
generation).

 

[Andrew Marlow]

Can someone recommend a good source of C/C++ coding style.
Specifically, I am interested in commenting style and in
particular how to indent comments and the commented code, rather
than when to use comments. Thanks in advance!

I think this is going to turn into a very long thread. I forsee everyone
and his dog chipping in with their $0.02. I can't resist either!

I have several observations about comments:

generally, less is more. The more the code is self documenting (sensible
identifier names etc) the less comments are needed. The shorter and
simpler an algorithm is, the less comments are required to explain it.

I prefer comments to be in the header rather than in the implementation
file. And I tend to make such comments suitable for doxygen. This way the
doxygen output provides virtually all the documentation required. Be aware
though that some people do not like this. They think it makes the header
very long (which, ahem, it does) and they don't like long headers since
they go to the header to figure out how to use the class. So this is down
to personal taste. But IMO there need to be doxygen comments *somewhere*.

Don't use comments to comment stuff out. Stuff that needs to be removed
should be removed. After all, you're using source code control, right? So
you can always get it back again if you need to. Stuff that you need to
switch on and off whilst you are developing it can be temporarily
commented out using '#if 0...#endif".

Placing C++ comments at the end of preprocessor directives is not as
portable as it ought to be. Some brain-dead compilers still insist that
any comments there are C style block comments. A distressing number of
environments are still forced to use these brain-dead compilers.

Regards,

Andrew Marlow
--
There is an emerald here the size of a plover's egg!
Don't top-post http://www.catb.org/~esr/jargon/html/T/top-post.html
Plain text mails only, please http://www.expita.com/nomime.html

[ See http://www.gotw.ca/resources/clcm.htm for info about ]
[ comp.lang.c++.moderated. First time posters: Do this! ]

 

[=?ISO-8859-15?Q?Juli=E1n?= Albo]

void f( )
{
// NOTE: There is a caveat in the following lines of code
...
// Here come more lines that do not have any caveats. How
should one make that clear? Should they be separated by a couple
of empty lines or what?
}

{
// NOTE: This note applies to the indented next lines.
something ();
somemore ();

anotherthing ();
}

 

[Seungbeom Kim]

class XX
{
public:
// LIFECYCLE

/**
* Default constructor.
*/
XX(void);

/**
* Copy constructor.
*
* @param from The value to copy to this object.
*/
XX(const XX& from);

/**
* Destructor.
*/
~XX(void);

// OPERATORS

/**
* Assignment operator.
*
* @param from THe value to assign to this object.
*
* @return A reference to this object.
*/
XX& operator=(XX& from);

// OPERATIONS
// ACCESS
// INQUIRY

protected:
private:
};

Do we really have to explain in comments what those declarations mean?
Every C++ programmer should understand that those are the default
constructor, the copy constructor, the destructor, the assignment
operator, etc. And roles of the arguments and the return values (if any)
should be obvious, and anything else should be avoided.

That style of commenting falls into the same category as this:

++x; // increment x

and I would object to it, unless the code is for exposition of the
relevant part of the language in a C++ textbook.

 

[noone]

A classic case of superfluous comments if ever a read one. The use of
(void) is also unnecessary and bad style in C++.

Sorry for not responding to the top-level post but I already erased it.

I hesitate to get involved in this discussion because coding style is so
subjective but I did have a couple comments to make that others might find
useful.

As a 40 year old manager of other software developers I have seen a whole
lot of coding styles in a bunch of languages over the years. Programmers
are still generally by nature a creative and sometimes hyper-sensitive
bunch who can take code review as a personal attack...so within reason I
tend to choose my battles and not dictate too much in coding style to
those I have working for me.

I have preferences and share those coding preferences with my
subordinates. However, the only things I really enforce are limiting line
length to an 80 column display and using comment markups that can be
preprocessed by doxygen. I want to be able to look at a webpage that
gives me adequate API information about their classes. If I cannot look
at the API doc and then make use of the class then the documentation is
not adequate. If a code review is necessary because of a bug, then I
might suggest to a programmer that a better or different coding style
would aid in finding the bug more quickly, if the circumstances support
that assertion.

Being a child of the assembler and fortran days I still tend to prefer
post-statement comments that start on the 40th column and I like code
blocks to be scoped in {} and blocked by

// ---------------------------------------------------

lines lines.

Indentation to me makes more sense on 4 character boundaries where spaces
(not tabs) are used and program flow follows that of a good outline
indentation scheme. I have no preference regarding whitespace in
expressions and deviate in style there myself.

 

[Angel Tsankov]

Being a child of the assembler and fortran days I still tend to

prefer
post-statement comments that start on the 40th column and I
like code
blocks to be scoped in {} and blocked by

// ---------------------------------------------------

lines lines.

Could you please comment the following pieces of code:

// The following function needs some description which occupies
2-3 lines

void f( )
{
// Block 1 needs to be explained in 2 lines:
stmt_1;
stmt_2;

// Block 2 need to be explaing in a single line:
stmt_3;
stmt_4;
stmt_5;
}

And now some real-world example:

///////////////////////////////////////////////////////////////////////////////
// A macro that evaluates to the size of an array, verifying that
its argument
// is indeed an array (and not a pointer, for instance):
///////////////////////////////////////////////////////////////////////////////

// First, a function template is declared to help verify that the
argument is
// an array:

template< typename T, std::size_t N >
T (& check_array( T(&)[N] )) [N];

// Then the macro is defined as follows:

#define SIZE_ARRAY( array ) (sizeof check_array( array ) / sizeof
(array)[0])

 

[kevin cline]

Basically attached is the class layout and source code layout... You
can see the comments section. Also if you want to comment a large
piece of code but at the same time you don't want to delete the code
use #ifdef like

#ifdef JUST_FOR_COMMENTING_OUT
code here which you dont want to execute
#endif

Hope this helps!

Satish

##############CLASS LAYOUT##########################
/**
* A one line description of the class.
*
* #include "XX.h" <BR>
* -llib
*
* A longer description.
*
* @see something
*/

#ifndef XX_h
#define XX_h

All the comments that follow are completely useless. They consume
screen space while adding no information, merely stating what is
obvious to a C++ programmer with more than a month's experience. Code
is much easier to read and understand when it is uncluttered.