Re: [boost] Re: Suggested coding guidelines

From: David Abrahams (david.abrahams_at_[hidden])
Date: 2001-07-06 19:37:17

----- Original Message -----
From: <williamkempf_at_[hidden]>

> Understandable.  My only complaint is that editors that do auto-
> indenting and/or treat the tab key as a sequence of spaces may not
> work nicely with varying indent sizes.

I don't have a good solution. Most of them also don't respond well to my
guideline that main namespaces should remain unindented, either:

namespace boost { namespace python {
class reference;
...
}}

I think it's roughly the same problem.

> > IMO vertical density makes reading code difficult. If you stick
> several
> > multi-line definitions next to one another, things tend to get too
> dense.
>
> Granted.  However, you can arrive with a different problem if you
> expand the vertical density too much, which this rule can lead to.
> I've never used this rule, but been careful to insure the vertical
> density remains at a level consistent with easy reading.  It just
> seems like this rule is a little too restrictive just to inforce
> another rule that should be more explicitly spelled out.  In other
> words, I'd prefer to see a rule about insuring the vertical layout is
> properly split into "paragraphs" for easy consumption.  (Granted,
> wording of such a "rule" will be difficult.)

I like the way you said it. I certainly don't follow those vertical spacing
guidelines consciously. Propose a specific change, and I'll consider it.

> Well, I'm not sure the number of spaces *should* be mandated.  As
> evidenced here, different people have different preferences for
> indent size.  As long as the size is consistent within a file should
> we dictate the actual size?

I don't know. It makes things easier if you have to muck about in someone
else's code, but that doesn't happen for most boost users.

> So all definitions would follow the form:
>
> void foo(
>   bar b)
> {
> }
>
> I hope this wasn't the intended interpretation.

I really don't know.

> I'm opposed to this for the same reason I'm opposed to the other
> variable sized indentation rules.  I'd much prefer to stick to a
> single indentation size (whether mandated or not) and leave these
> unindented.

Would you object to "zero or one"?

> > > 5.7  I find this a little restrictive with the reasoning being
> > > questionable.  That said, I can live with it.
> >
> > Here's an example of the alternative:
> >
> >
> >     if (x < 0)
> >         x = 0;
> >     else
> >     {
> >         for (y = 0; y < x; ++y)
> >             do_something();
> >
> >        do_some_other_thing();
> >     }
> >
> > My eye says that the x=0 goes with the 'if' clause and the rest is a
> > separate entity like a struct declaration or a while loop. This is
> an
> > aesthetic consideration; others' taste may not coincide here.
>
> Mine don't, but I realize this one is purely aesthetic, that's why I
> can live with the rule.  However, since you agree that it's purely
> aesthetic, and aesthetics are in the eye of the beholder, should we
> really dictate (even in "optional" guidelines) this?

I don't know.

> > > Also, the comment
> > > about being consistent with compiler error messages is, frankly,
> > > misguided.  We can't predict how compilers will display this sort
> of
> > > message.
> >
> > Except that compilers have to go out-of-their way to
> generate "const char"
> > instead of "char const" when they also have to generate "char*
> const". If
> > you pick a simple algorithm to translate an internal type
> representation
> > into valid C++, it will always put the const afterwards.
>
> Granted.  However, since the standard doesn't dictate this Murphy's
> law says there will be an implementation that behaves differently
> from what you'd expect.  I'd rather not document this at all, but if
> you're going to make it obvious in the wording that you're just
> expecting *most* compilers to generate such errors.

OK. It also makes it a little easier to reason about what a type declaration
means, if you're not already used to "const char". The rest of us are just
well-accustomed to an inconsistent style.

> > That said, I still have a hard time adjusting to writing "char
> const". OTOH,
> > if you have to pick a rule, it should be a consistent one. The
> alternative
> > is no rule: some people write "char const" and others write "const
> char". Do
> > we care?
>
> Personally I don't.  If we have to pick and it's up to a vote I'll
> vote for "const char", but I'm used to adapting styles according to
> guidelines I don't always agree with. :)

I might prefer having no guideline, but let's hear from the group.

> > > 7.3 & 7.9  Though they technically don't conflict, they lead to
> > > confusion because of their differing emphasis on accuracy or
> brevity.
> >
> > Yes, they are explicitly recognized as conflicting goals. Do you
> have a
> > suggestion?
>
> Other than putting text in that states what you just did, no.  I
> understand there's a trade off here and the programmer has to try and
> achieve as much of both goals as he can.  The problem is, both rules
> currently read as mandates rather than goals, and given the conflict
> you can only fully meet one mandate.  I'd suggest lessening the
> emphasis or combining the two into a single rule stating that you
> must strive for terseness while being complete.

I think the document accomplishes that, but would be open to your proposed
patch, as always.

> > "Function definitions in the class body are forbidden"
>
> I can't always apply this rule with VC++ :(.

I realize that, for member templates. Portability concerns will always
dictate exceptions to this rule.

> > > 12.2  What does this mean for Boost where the convention is to put
> > > all code in the boost namespace?
> >
> > I think the emergent rule for boost is: separate domains go in
> their own
> > sub-namespaces. General-purpose code goes in boost. Probably 12.2
> should be
> > changed to reflect that fact.
>
> I realize it's "emerging", but is that really the current desire?
> I'm asking because I'd like to know if the Boost.Threads stuff should
> be in boost::thread before I submit (would this cause any conflicts
> with the thread class name?).

I don't know.

-Dave