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!
--
[ See http://www.gotw.ca/resources/clcm.htm for info about ]
[ comp.lang.c++.m oderated. First time posters: Do this! ]

[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_COMMEN TING_OUT
code here which you dont want to execute
#endif

Hope this helps!

Satish

##############C LASS 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::operator=(X X&);
{
return *this;

}// =

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

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


Angel Tsankov wrote:

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!

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

[mlimber]

[cross-posting deleted]

Satish wrote:

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_COMMEN TING_OUT
code here which you dont want to execute
#endif

Hope this helps!

Satish

##############C LASS 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::operator=(X X&);
{
return *this;

}// =

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

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


Angel Tsankov wrote:

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, please don't top-post here (see
http://www.parashift.com/c++-faq-lit....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-lit...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++.m oderated. 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.

--
A: Because it messes up the order in which people normally read text.
Q: Why is it such a bad thing?
A: Top-posting.
Q: What is the most annoying thing on usenet and in e-mail?

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

Alf P. Steinbach wrote:

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.

--
Salu2

[Noah Roberts]

Angel Tsankov wrote:

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/articl...&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.
--
[ See http://www.gotw.ca/resources/clcm.htm for info about ]
[ comp.lang.c++.m oderated. First time posters: Do this! ]

[Rolf Magnus]

Alf P. Steinbach wrote:

* 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.

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:

Alf P. Steinbach wrote:

>* 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.

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
condititiona l 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++.

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".

>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.

It's practical.

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

--
A: Because it messes up the order in which people normally read text.
Q: Why is it such a bad thing?
A: Top-posting.
Q: What is the most annoying thing on usenet and in e-mail?

[BobR]

Alf P. Steinbach wrote in message ...

>* Rolf Magnus:

>>And it's a shame that /*...*/ don't nest, necessitating using
conditition al 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++.

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>

--
Bob R
POVrookie

[Ian Collins]

Satish wrote:

/**
* 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++.

--
Ian Collins.