Boost logo

Boost :

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

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

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

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

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

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

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

Bill Kempf

Boost list run by bdawes at, gregod at, cpdaniel at, john at