Re: [boost] Review: Boost Coding Guidelines

From: Paul Baxter (paul_baxter_at_[hidden])
Date: 2001-07-17 05:38:01

My vote goes to accepting the Coding guidelines document albeit with a
couple of concerns.

I am concerned that they might be used as a rod to control future
submissions, but feel that the good advice within is a valuable resource.
Mind you the existing library guidelines already do this to some extent with
no ill feeling so far.

I would like to see (eventually) the documents refactored to include a
Boost-specific library policy (featuring things like commenting policy,
licensing, config policy), a set of 'standard' coding practices (probably
quite short and comprising advice like use the standard library, header
issues) and a further set of supplementary guidelines.

It may even be suitable to go further and separate stylistic guideline
issues from engineering issues.

Engineering guidelines provide a method (or methods) to help ensure that
code works robustly even though there may of course be other robust methods
e.g. noncopyable vs explicit hiding of assignment and copy constructor.

IMHO stylistic issues relate to easing the readability of code through
naming, commenting, spacing etc. (Whether variable/class naming is only a
stylistic issue may be open to debate.)

I don't think refactoring is a short task and is outside the remit of this
review. I hope that the content of the actual guidelines is what is being
reviewed such that at a later date they can be incorporated within the
existing documentation rather than as a separate overlapping document. For
now the slight overlap though confusing, is manageable.

A submission to Boost should meet the requirements of the Boost-specific
policies (albeit possibly to be implemented after review and before
acceptance). It should also meet the standard practices unless a contrary
rationale is provided and accepted. It may not necessarily meet all of the
coding guidelines and stylistically it may vary.

In summary
Boost Policy - mandatory for Boost irrelevant elsewhere
Coding Standards - mandatory for all
Coding Guidelines - a guide to good engineering practice but not mandatory
Stylistic guidelines - affects the readability - optional but needs
consistency throughout a project

The idea is that another project would just replace the Boost policy layer
and possibly provide its own Stylistic layer. It may also add supplemental
coding guidelines.

As an aside surely there is a stage beyond syntax highlighting where an
editor can be configured to handle different spacing/tabbing requirements
automatically.
(Indent and other programs I've seen go some of the way, but leave out
things like where brackets go around control blocks like 'if' statements.)

Paul Baxter