Re: [boost] Re: Review: Boost Coding Guidelines

From: David Abrahams (david.abrahams_at_[hidden])
Date: 2001-07-17 08:27:39

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

> I'm going to add my voice to Paul and Mark for rejection here.  When the
idea of
> coding guidelines was originally raised I thought it would be a good idea.
> However, the content of the current guidelines isn't at all what I believe
would
> be consistent with boost.  I was interested in rules of thumb that improve
the
> quality of written code.  Each guideline item conveying a clear rational
and
> example.
>
> I believe sections 3-5, 7 and 10 should be removed because all the
elements
> discuss code formatting and commenting.  By definition, these are targeted
at
> human readers and at some level will become "religious issues".  At the
very
> least, these are going to get in the way of accepting the useful stuff.

I don't think that code formatting and commenting are irrelevant to quality.
Source code is fundamentally there for communication with human readers.
Otherwise we'd just compile it and throw the source away. Other major
successful open-source projects (e.g. GNU) have formatting standards. That
doesn't prove it's a good idea for boost, but it does prove that it's viable
and that some people even consider it important.

BTW, on the subject of bracing styles, I think my previous posts were not
very clear: I don't object strongly to K&R bracing:

if (x) {
   ...
}

so long as there's warning to be conscious of the dangers of vertical
density.

> And there are problems in other places.  Just to pick one guideline out of
the
> group as an example:
>
> 11.16.    Step through each line of code you write or change in a
debugger. This
> includes error-handling code. It is OK to artificially stimulate error
> conditions for debugging purposes. See ``Writing Solid Code.''
>
> This is silly.  No one has time to bother making sure that something like
>   int i = 10;
> will work.  And besides, there are plenty of ways to validate program
functions
> that have nothing to do with using a debugger.  This is really a
project/testing
> guideline not a coding guideline.

This guideline was not designed with boost in mind, and I wouldn't mind
striking it. There are probably a few others of the same nature.

> So, while I haven't had time to read the detail of every last guideline
(let
> alone follow the entire thread) I don't think the current guidelines can
get the
> high standards of boost without major rework.
>
> And finally, with the All Rights Reserved copyright, anyone that wants to
modify
> the guidelines for their own purposes, will have to ask David and Nathan
for
> permission.  This would be the only item in boost with this standard.  I
have
> absolutely no problem with David and Nathan wanting to maintain rights to
> publication etc, but then they shouldn't be part of boost.  In my opinion
they
> should have the same rules as code to be accepted into boost:
>
> -->Must grant permission to copy, use and modify the software for any use
> (commercial and non-commercial) for no fee.

FWIW, the plan was to change that to something more suitable.

Finally, I have no axe to grind about getting these guidelines, or a variant
thereof, accepted into boost. If they are rejected, I will only wish that
the formal review had begun earlier so that I wouldn't have spent so much
time on them here.

-Dave