Re: [boost] Suggested coding guidelines

From: David Abrahams (david.abrahams_at_[hidden])
Date: 2001-07-03 13:19:09

----- Original Message -----
From: "Ed Brey" <edbrey_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?

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

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

That was what I thought you had proposed.

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

Phew!

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

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

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

> From the
> standpoint of practicing what one preaches, the guideline document
> should be careful to make sure it obeys all its own rules.

Agreed. Thanks for pointing that out.

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

They're common English words; you can check the dictionary. The coding
standard means what it says.

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

-Dave