Re: [boost] Suggested coding guidelines

From: Ed Brey (edbrey_at_[hidden])
Date: 2001-07-03 14:19:27

From: "David Abrahams" <david.abrahams_at_[hidden]>
>
> > 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.
>
> I don't agree with your conclusion, but even if I did you would be
> contradicting yourself. If mangling only ensures uniqueness in a small
> fraction of cases, it isn't reliable.
>
> >   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.
>
> I don't understand your math.
>
> Are you saying that just because we can't afford to mangle most
macros, it
> isn't worth ensuring success with the macros we can mangle?

Yes, if in the final tally, the number of error with mangling is
approximately equal to number of errors without mangling, then the
mangling isn't worth it.  (Note that this does not preclude mangling
being useful for other reasons, such as reducing maintenenace during
restructuring.)

> I don't want to have that argument. It seems entirely too pedantic.

Iroincally, the point of the argument is that the mangling itself is
pedantic, since it involves effort and rules with little tangible
result.

> > > >  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.
>
> Doesn't this argue for mangled #include guards? Forgive my
frustration, but
> You seem to be arguing in circles! At one point you seem to say that
> consistency is more important than success; at another you seem to say
that
> we should take steps to succeed where we can.

A very good point.  Consistency and determinism are both desired
attributes, and occasionally they come into conflict.  Without thinking
about it, I naturally favored consistency within the macro problem
class, since all macros abide by the same (lack of) scoping rules.
However, there are two classes of macros in this domain, (1) include
gaurds and (2) all others.  One can make the trade off to not treat them
consistently in order to reap more determinism.  However, if such reaped
determinism is very small, the consistency of treating all macros more
similiarly is more valuable.

> > 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.
>
> It also is easier than remembering exactly which contexts you're
allowed to
> use names starting with underscores. A simple rule, if not overly
> restrictive, is more powerful than a complicated one.

True.  But it is also easier to read (for me) _member than m_member in
code, and there is a tradeoff.  I think the documents selection of
forbidding the leading underscore and calling for m_ is fine, but as
with any tradeoff, it is very valuable to include the thinking behind
it, so it is easier to determine when, if ever, a different choice
becomes in order.

> > Fair enough, although a discussion of where one bends the rules for
the
> > sake of convenience/productivity would be interesting.
>
> I don't ever do that intentionally. I learned long ago that bending
the
> rules here or there at a whim tends toward code rot. Eventually your
program
> grows such that all of your acceptable violations become unacceptable.
This
> happens insidiously, so they never get addressed.
>
> People will make their own judgements about following and enforcing
any
> coding standard. Trying set out guidelines for when the rules should
be
> followed just strikes me as a complete waste of my breath.

True.  About all you can say is what you mentioned in your warning in
the first paragraph.  It might be worth mentioning somewhere, as
developers may not tend to think about the situation creeping ugliness.

> > 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.
>
> They're common English words; you can check the dictionary. The coding
> standard means what it says.

That "forbid" is a common English word is exactly why I raised the
point.  To me "forbid" means "never", which left be confused for a while
as I was reading the guidelines until I pieced together a deduction of
the authors' intent.  I don't connote any sense of exceptionalism with
the word.  As such, the out-of-the-box meaning of forbid doesn't fit
well with the guidelines intent, which is "don't do this without a
demonstratable need".

> > 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.
>
> Humans can invent sufficiently self-justified "demonstrable need" for
any
> number of atrocities. I am not interested in being a lawyer. If this
is what
> is required, I would rather withdraw the coding standard from
consideration
> at boost.
>
> > 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.
>
> If you want to write a preamble that describes "forbidden" and "avoid"
and
> everything else, by all means, do so. I doubt it would strengthen the
> document; in fact I think it would weaken it. Maybe others will feel
> differently.

Maybe a better approach is to use a word that conveys the intent
out-of-the-box.  Personally, I think "abstain" would do the job.  So
depending on how uncommon are situations where the rule should be
broken, the guidelines can say to abstain from x or avoid y.