Boost logo

Boost :

From: Paul Baxter (paul_baxter_at_[hidden])
Date: 2001-06-30 09:36:10


A few minor comments on the coding guidelines.

Firstly, thanks Dave and Nathan for making this available.

a) Section 1 - Perhaps add guideline about when to use #include
"myheader.hpp" instead of <myheader.hpp> Just to clarify system/library
headers vs user's headers.

b) Example after 1.8

Confusing use of Rectangle and rectangle

#endif // should end with HPP_ not H_

c) 2.1/2.2 Confusing to use vhdl_ams_parser as both examples

Maybe use HdlParser in the second?

d) Consider having a general section for layout before specifics of
definitions/blocks etc.

e.g for no tab rule

Ident in 2/4 space blocks (except 'public:', 'private:' I guess)

e) 4. Spacing of definitions and declarations

Resolve: In various places you use 1 space, two spaces, three spaces or
four. I find this confusing.

e.g. hpp/cpp files at end of section 4

Perhaps the spacing lost something in translation to HTML?

Whatever the result I'd like a consistent policy between the guidelines and
the examples.

f) Why
namespace altra {

instead of
namespace altra
{

when you use
class catalog
{

Example 4 hpp ends with a comment // namespace manhatten::database when it
opened altra::device_db

g) 6.5 Perhaps qualify this by acceptable reuse of loop variables and
possibly pointers/iterators i.j.k, p and q especially since they often go
out of scope after the end of say the for loop (??)

h)
>
6.6. <part snipped>
Declaring a value-parameter const has no effect in a function declaration
and is meaningless to the caller, so leave const off here - use it at the
point of function definition instead.
double f(double x, double y); // declaration
   ...
double f(double const x, double const y) // definition
{
    // x and y don't change in the function body, so
    // we know the original values are always accessible
}
<
Not sure I like this. Prefer to see const in the declaration as well. (Must
admit I didn't even realise this was permissable)

i)
> 7.1 Use ``//'' to delimit comments in lieu of ``/*.*/'' <
Rationale for this please.
I guess the issue for me is whether the source/header should sometimes be
used to document a design as well as clarify details of its coding
implementation.
If it is sometimes permissable to provide long comments discussing the
design, the use of multi-line comments is convenient and does not obscure
the text as much as // every line.
(Dare I say that most people now use syntax highlighting to avoid some of
the problems with missing the closing */)

In particular the use of class documentation tools like doxygen although
possible with '//' is far more convenient with the /* */ form.
I'm not going to get too upset if you disagree, but how can '//' at the
start of each line help when reading a multiline comment.

j) 12.2 and 12.4 seem to conflict.

General comments

Include a version or issue date for the guidelines document to help keep
track of any revisions.

The document covers a lot of ground and I am concerned that a few parts of
later sections require considerable in-depth knowledge of c++ to be of use.
e.g. Discussions of basic and strong exception guarantees are quite advanced
and may be better served by references to other works.

Whilst I understand it is not practical to go into the background and detail
of some of these statements, it may be necessary for programmers who are not
as familiar with recent C++ facilities to dig a little deeper to understand
things. Adding a short bibliography might be enough?

I feel the basis of a very useful book here :)

Paul Baxter


Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk