Re: [boost] Suggested coding guidelines

From: Vesa Karvonen (vesa.karvonen_at_[hidden])
Date: 2001-07-01 07:36:34

[I haven't read all the other comments, so some of these might be mentioned
earlier.]

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 coding conventions that
we use at work only specifies the decoration of different type of identifiers.
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.

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.

The guidelines suggest that template parameters should be in mixed case
without underscores. I have several issues with this:
- I very much prefer consistent use of underscores regardless of
capitalization.
- I also find identifiers with underscores easier to read regardless of
capitalization.
- One letter words obscure mixed case identifiers without underscores.

  Example for previous issues:

    ASomewhatDifficultToReadIdentifier

    A_Significantly_More_Readable_Identifier

- 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).

"8.9. Do not write the `inline' keyword on member function declarations"
- I recall observing (IIRC, I inspected the disassembly after having link
errors) that some compilers do not inline such functions. (IIRC, the compiler
was some version of MWCW.) So, I would generally advice against this practice
if portability is desired.

----- Original Message -----
From: "David Abrahams" <david.abrahams_at_[hidden]>
To: <boost_at_[hidden]>
Sent: Friday, June 29, 2001 19:08
Subject: [boost] Suggested coding guidelines

> See http://groups.yahoo.com/group/boost/files/boost-coding-standard.html
>
> These are the standards I use at work. I posted these since a few people
> expressed interest. They are not intended to act as requirements for boost,
> but as "guideposts to uniformity", for those without a preference in some
> issues and those willing to change. In fact, I think it would be worth
> discussing what role they should play at boost and how (whether) they should
> be presented.
>
> I have tried to ground most of the choices in engineering merit, but
> obviously many are to some degree a matter of preference. If people find
> actual problems with these, I'm certainly open to being convinced that there
> is a better way. Please keep in mind, however, that discussion of such
> issues can often become a kind of ``religious war'' and I think it would be
> a shame for boost to expend any energy on that.
>
> -Dave
>
>
> Info: http://www.boost.org  Unsubscribe:
<mailto:boost-unsubscribe_at_[hidden]>
>
> Your use of Yahoo! Groups is subject to http://docs.yahoo.com/info/terms/
>
>
>