Review: Boost Coding Guidelines

From: Beman Dawes (bdawes_at_[hidden])
Date: 2001-07-20 11:01:39

I think that Boost Coding Guidelines should be accepted, but subject to 
refactoring into separate "Requirements" and "Guidelines" documents. The 
refactoring should include material from the current "Library Requirements 
and Guidelines" page, http://www.boost.org/more/lib_guide.htm, and perhaps 
one or two other current pages.

Vesa Karvonen's comments are well worth repeating:

    The style/terminology of a guidelines document should be different
    from the style/terminology of a requirements document. A requirements
    document describes what is required. A guidelines document describes
    what is recommended (sometimes strongly). A guidelines document should
    not use phrases like "is required" or "must be".

    In principle, violation of requirements should be grounds for rejection
    of a library, although singular violations could be accepted by group
    consensus. On the other hand, violation of (a few) guidelines should
    never cause rejection of a library, although violation of numerous
    guidelines could be considered grounds for rejection by group 
consensus.

The second of the two paragraphs above might be included in the preamble of 
both requirements and guidelines documents, together with a link from each 
to the other.

Although I usually hate all uppercase text, to help meet concerns expressed 
in the formal review, I think the guidelines document should begin with an 
all uppercase imperative similar to Dave Abrahams' current lead sentence, 
such as:

THESE GUIDELINES ARE NOT INTENDED TO BE USED AS REQUIREMENTS FOR ACCEPTANCE 
OF PROPOSED BOOST LIBRARIES.

I don't think another formal review is required after refactoring, but I do 
think drafts of the documents should be posted for comments, so that 
someone can object if they think a particular requirement or guideline is 
mis-categorized.

I'll volunteer to help with the refactoring, particularly as it would 
effect current Boost web pages.

--Beman