Re: [boost] Suggested coding guidelines

From: David Abrahams (david.abrahams_at_[hidden])
Date: 2001-07-03 11:44:21

----- Original Message -----
From: "Ed Brey" <edbrey_at_[hidden]>

> For me the interested was generated from a natural longing for
> consistency.  The theory goes, if mangling is a good thing, it's a good
> thing, so why not BOOST_DECL_MGL121200?  The answer of course is that
> most macros are referenced in potentially many places, whereas macro
> guards are only referenced in a handful of places

No, they are referenced in only ONE PLACE (unless you believe in checking
#include guards before #including -- I do not).

> so mangling is
> practical for header guards.  The longing for consistency raises the
> real issue is that, even though there is little harm in mangling, is
> there even less benefit

Why do you say that? Some method must be found to ensure uniqueness.
Mangling does that reliably.

> , such that it's not worth it.  Header macros are
> just one link in a the macro chain, and yes, strengthing it does provide
> benefit; however, it seems too small to be worth even minor
> inconvenience.

1. Leaving off #include guards would be convenient
2. Having them at all is a minor inconvenience
3. Having to do something to ensure uniqueness is even more of an
inconvenience

Where do you propose we stop on this list? I think #3 is the only acceptable
stopping point, or all of our work to keep C++ names unique is worthless. If
you are just arguing about the precise form of what is done to ensure
uniqueness, then I disagree with you about convenience. I think
initials+date is a bit more convenient than your proposed method. Also it is
immune to project restructuring.

> The other reason I think this topic generates such interest is that a
> design pattern that mangles some macros, but not all, is engaging in
> probabilistic engineering, which is unreassuring.  One longs for a
> solution that guarantees success.

Forget it: there are no such solutions in the C++ world. Nobody in the world
has promised not to use namespace boost either. Maybe you would be happier
with a Java-like system? In Java, namespaces are arranged according to web
addresses or something.

> Now that I've had a chance to look over the document, I have a few other
> comments.
>
> First, it is very good overall - quite well laid out.

Thanks.

> The rationale for not using /* */ to comment out code mentions that the
> syntax highlighter won't pick up a problem due to lack of comment
> nesting.  My experience is that the syntax highlighter does this just
> fine.  When you insert the closing */, iff the code above it isn't
> comment-colored, you have a problem.

It depends how it's done (in emacs I could select from end to beginning and
use a command to surround it with /*...*/), but your point is taken.

> 2.14, "Names containing double underscores", seems overbearing.  Why not
> forbid a prefixed single underscore only when it will result in
> undefined behavior?

We've just had the discussion on the boost list about this. In practice,
system headers define these symbols as macros even when they shouldn't.
People have been reporting problems.

> 6.6, "Use const whereever possible": The wording is too strong.  While a
> good idea in general, for small functions, it is sometimes more trouble
> than it worth.  For example, the example at the end of section 4 should
> be "int f(int const x) {return x+1;}" given this rule as written.

People will ignore/overlook the rules in cases like this. It's very hard to
write good rules with exceptional cases. Anyway, there is no need for an
exception in this here: I would probably write f as above if I wasn't paying
attention but if someone took the trouble to point out that I should add
const, I would do it.

> 8.2 "Make all data members private": What is the rationale for the
> strength of "Protected data members are forbidden." versus saying simply
> to avoid protected data members?

Same as the above. You never /need/ protected data members. Less-advanced
programmers tend to use them because they see them in other peoples' code.
It's better to have absolute rules that only get broken when there's a
demonstrable need than to have a bunch of watery recommendations that will
be ignored by people who don't know better.

> 8.4 "Function definitions in the class body are forbidden". It is my
> understanding that a function that soes nothing but expose a constant
> version of a member variable is quite reasonable to declare within the
> class definition.  Any reason why this usage is not mentioned here?

Because it's forbidden. Every implementation detail you expose in the class
body obscures the interface.

-Dave