Re: [boost] Suggested coding guidelines

From: Vesa Karvonen (vesa.karvonen_at_[hidden])
Date: 2001-07-03 07:20:04

From: "David Abrahams" <david.abrahams_at_[hidden]>
> From: "Vesa Karvonen" <vesa.karvonen_at_[hidden]>
>
> > In C++, indentation/layout does not prohibit from interfacing a piece of
> code
> > with another piece of code. Therefore indentation guidelines are
> significantly
> > less important than identifier decoration rules.
[...]
> > The most important indentation guideline is to avoid using an indentation
> that
> > is difficult to maintain. An example of a difficult to maintain layout is
> the
> > endline layout.
                    Endline layout is described in the book Code Complete by
 Steve McConnell.
>
> Agreed. Would you like to suggest a change based on this?

How about reformatting and adding the above text to document?

> > The guidelines suggest that include guards should be unique, and then
> suggests
> > using a date and name. Another alternative is to use a 128-bit GUID per
> > project. Using a GUID offers a considerably higher level of protection
> against
> > collisions. We use a single GUID for all of our libraries, which
> internally do
> > not have collisions, at work and I don't recall having any collisions with
> any
> > other library ever.
>
> I think this places too high a burden on the programmer, and that the
> proposed method is sufficiently unique. I don't even know how to make a
> GUID!

I don't know the exact algorithm for producing them either, but I can get them
on my machine by using the guidgen application. I'm not an expert on COM, but
I'd assume that it has a service for generating GUIDs.

Eventhough it can a burden to generate a GUID for every separate header or
even every separate library, it might be a reasonable approach to generate a
single GUID to be used in every Boost include guard. This could be extremely
effective in shielding Boost against other libraries.

> > The guidelines suggest that template parameters should be in mixed case
> > without underscores. I have several issues with this:
[...]
> I agree with you about the readability part, but the guideline is designed
> for consistency with the boost:: and std:: legacy.

Which specified (as opposed to unspecified, undefined or implementation
defined, etc...) legacy std:: names are in mixed case without underscores?

It seems to me that the decoration of template parameter (or function
parameter) names is not specified in the C++ standard.

> > - IMO, parameters should be consistently decorated the same as local
> > definitions - like in normal function definitions. I have broken this
> > principle recently, due to differences in Boost conventions (uses lower
> case
> > typenames) and the conventions I use at work (mixed case typenames), and
> > noticed this only recently. In future, I will consistently decorate
> parameters
> > the same as local definitions, also in my Boost libraries, regardless of
> the
> > type of the definition (whether it is a metafunction, function, class or
> > whatever).
>
> I need an example to understand this. I think my guidelines are consistent
> in this regard (?)

Consider the following code snippet:

  void f(int p0, int p1)
  { int l0, l1;
  }

As you can see, the parameters p0 and p1 are decorated/capitalized the same as
the local definitions l0 and l1.

Likewise, I prefer to use the same style consistently in metafunctions and
other parameterized constructs also:

  template<class p0, class p1>
  struct metaf
  { typedef ... l0;
    typedef ... l1;
  };

Decoration should be based on type!

Template type parameters are essentially (holders for) types and they should
therefore be decorated the same as other type definitions.

It is most unfortunate that the conventions used in many books use a distinct
decoration for template parameters. This is probably because templates were
considered so special at the time and hiliting the parameters was helpful in
reasoning about the code.

> These guidelines are
> designed to be used up until the time you prove that something else is
> neccessary.

That is a sensible approach.