Re: [boost] Suggested coding guidelines

From: Ed Brey (edbrey_at_[hidden])
Date: 2001-07-03 12:46:49

From: "David Abrahams" <david.abrahams_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).

Checking before #including is what I was referring to.  I don't do it,
but I respect that others do.

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

I agree that mangling does reliably ensure uniqueness, which is a real
benefit.  The problem is that the benefit applies only to a fraction of
the macros that use mangling.  Consider that the probability of success

    Ps = product(1 - P(collision(macro[i])), i=0..macro_count)

will be improved only slightly by mangling if any of the following is
true:

    (a) macro[i] is mangled for few i.
    (b) Where macro[i] is mangled, P(collision(macro[i])) is very close
to the non-mangled probability.
    (c) A combination of mostly-true (a) and (b).

Note that (b) refers to a possibility that conflicts are more likely to
occur for macros like BOOST_DECL than BOOST_SMART_PTR_HPP, and so the
mangling is being applied to the less troublesome candidates in the
first place.

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

I don't remember proposing a method, although if I did, I'd be tempted
to say BOOST_relativepathname_filename format (all caps, of course).
The only caveat is regarding product restructuring, as you point out.
That seems like reasonable justification to replace relativepathname
with some unique code (e.g. initials and date).

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

I prefer to remember it and strive for it, but not count on it.  Even if
not achievable across the board, the more aspects of a design that can
be made deterministic, the better.

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

I am aware of the discussion.  I was curious whether the problem reports
were the sole justificaiton for the rule.  It's a lot of ground to give
to appease a few broken compilers.

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

Fair enough, although a discussion of where one bends the rules for the
sake of convenience/productivity would be interesting.  From the
standpoint of practicing what one preaches, the guideline document
should be careful to make sure it obeys all its own rules.

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

What would be really valuable is a characterization of a "demonstratable
need", but such is probably not possible.  Short of that, definitions of
"avoid" and "forbidden" would be very helpful.  Speficially, it would be
helpful to mention that "forbidden" rules should be broken only when
there is demonstratable need to do so.  Without such definitions, a
reader may think they the rules should never, ever be broken out of fear
of some terrible unknown problem popping up.  Or on the other hand, a
reader may see find what he believes (and truly is) to be a clear reason
to do what is forbidden, and assume that the guidelines must be somewhat
arbitrary and not well thought out, since they forbade a reasonable
action.

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

Agreed.  Here again, I'm curious to hear if how people find the
convenience (and productivity?) of not defining the function separately
trades off against the interface obscurement.