Re: Suggested coding guidelines

From: williamkempf_at_[hidden]
Date: 2001-07-06 12:51:48

I'm going to throw my comments in on this document.  First, let me 
say that most of the guidelines are the very same ones that I use for 
most of my coding (when other guidelines don't dictate otherwise).  
So I very much like what's here.

Now for specific comments:

1.6  Does this bar comments from being placed above the #includes and 
#include guards?

4.1  Should the guidelines specify the number of spaces used for an 
indentation level?  If so, should it be consistent for all 
indentations?

4.2  Should the example (code that reads "template <class T> void f
(T);") follow this rule?

4.4  Why?  As long as all lines but the first in a multi-line 
definition is indented another level the blank lines add little 
benefit, and in fact can detract from the rest of the code.

4.5  See 4.1.

4.6  Wording should indicate this applies to multi-line definitions.  
As written it means that ALL function definitions should be multi-
line.  Also, see 4.1.

4.7  Again, why?

4.8  Why?  Also, see 4.1.

4.9  Not sure I like the inconsistencies.  Also, the example uses 
both template<> and template <>. Should there be a rule for this?  
Even if not, the examples should be consistent.

5.3  See 4.1.

5.7  I find this a little restrictive with the reasoning being 
questionable.  That said, I can live with it.

5.8  See 4.1.

6.7  This makes the code read less like english.  Also, the comment 
about being consistent with compiler error messages is, frankly, 
misguided.  We can't predict how compilers will display this sort of 
message.

7.2  Should read "comments refer to code to the left on the same line 
or below them."

7.3 & 7.5  Don't quite work well together.  Combining them will 
better explain that public and protected interfaces should be fully 
commented at the point of declaration.

7.3 & 7.9  Though they technically don't conflict, they lead to 
confusion because of their differing emphasis on accuracy or brevity.

7.12  It would be helpful to have a document listing the proper C++ 
terminology and improper variants.

7.15  Commenting out code should be avoided.  Yes, there are times 
when this rule can be broken, but generally it's better to rely on 
the configuration management tool (CVS for us) for recalling code 
that's been removed.  Commented out code simply makes reading more 
difficult.

8.1 & 8.2  Though use of public and protected data members may be 
questionable from a design stand point, this is a coding guidelines 
document not a design guidelines document. (Boost should have both, 
but the coding guidelines should be careful to not discuss any design 
guidelines.)

8.3  Also a design guideline, though the rule about friend being 
close to code meant to be exposed is worth retaining.

8.4  Why make an exception for operator()?  The reasoning given just 
begs the question since the word "often" is used.  What about the 
other cases?  What about in template classes?

8.7  Why?  The grouping and commenting I can agree with, but leaving 
off the virtual can lead to confusion for readers not fully versed in 
C++.

All of 9 & most of 11, 13, 14 and 15 should be in a design guideline 
instead.

12.2  What does this mean for Boost where the convention is to put 
all code in the boost namespace?

Bill Kempf