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

From: Vesa Karvonen (vesa.karvonen_at_[hidden])
Date: 2001-07-18 16:55:20

From: "Mark Rodgers" <mark.rodgers_at_[hidden]>
[...]
> That's what I said.  We should only mandate external details such as
> those that may find their way into a standard.

I agree. There should be a very clear distinction between requirements and
guidelines.

[The following are just my opinions.]

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.

Both kind of documents should be packed full of proper references to
literature. A comment such as "Every C++ textbook -- I have 10 here, not
counting C books --" is not, IMO, appropriate in a requirements or guidelines
document, because the style is too personal.

Such documents (requirements and guidelines) should be accepted or rejected
based on whether they are *needed* by or extremely useful to library *authors*
or not. Library users and the C++ community are important, but Boost should
not even try to impose any requirements or even guidelines for anything but
Boost library authors.

Personally, I think that there is need for a more detailed requirements
document, with examples, than the current "Library Requirements and
Guidelines" page (http://www.boost.org/more/lib_guide.htm). A guidelines
document could also be useful for library authors, but not nearly as important
as a requirements document.