From: Greg Chicares (chicares_at_[hidden])
Date: 2001-06-29 18:53:58
David Abrahams wrote:
> 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.
I felt trepidation but didn't express it. I am pleasantly surprised.
I've read every coding guideline I can find, and this is the only one
I don't have religious issues with. It's nicely written too.
> [...] In fact, I think it would be worth discussing what role they
> should play at boost and how (whether) they should be presented.
I see this as a useful expansion of
more/lib_guide.htm#Design and Programming
and would recommend incorporating it there by reference, perhaps
with a hyperlink in this bullet point:
'Follow quality programming practices. See, for example,
"Effective C++" 2nd Edition, and "More Effective C++", both
by Scott Meyers, published by Addison Wesley'
[begin addition] 'and these guidelines by David Abrahams and
Nathan Meyers' [end addition]
| Table of Contents
| 6.Declarations and initialization
| 7.Comments and Documentation
Suggest capitalizing only the first letter in items 7, 8, 10, 14.
| 1.2 #ifndef RECTANGLE_DWA050499_HPP_
Could I persuade you to use ISO8601 dates instead? I have to think
about whether this means
| 1.1. Change logs, if used, appear at the bottom of files. A source
| file's primary role is as documentation of the current state of the
documentation of the <i>current</i> state
I personally had trouble parsing this until I realized 'current' is
the key word.
| 1.5 Of course, this technique's effectiveness is mitigated by the
extent to which (generic) code appears in header files. [context:
include class header first]
I'm not sure I follow this. Does 'generic' mean 'templates', or just
something like 'reusable'?
| 1.7 Don't change your designs just for the sake of this guideline
[context: avoid #include in headers when forward decl will do]
I make this guideline a requirement in code reviews. I can't see a
reason for not complying: changing the code is easy. What am I missing?
Would s/Don't/You need not necessarily' preserve the spirit?
| 1.7 Of course, this technique's effectiveness is mitigated by the
extent to which (generic) code appears in header file.s
Same question as for 1.5 above, and change 'file.s' to 'files.'
Spacing after the section numbers is not uniform. Also occurs elsewhere,
e.g. 4.6 vs. 4.7 .
| 2.14 Names containing double underscores (``__'') are entirely
Isn't '_A' as bad as 'A__1'? IOW, why mention only one of the
cases in 22.214.171.124.2 but not the others?
| 3.5 all uses of ``&'', ``|'', ``<<'', ``>>'', and ``^'' should be
[Context: 'Fully parenthesize uses of bitwise operators']
Would you allow an exception for streaming operators?
std::cout << x * x << s + s << '\n';
Does the context imply that that's OK?
| 3.6 return is not a function; do not put parentheses around the value
being returned. This also goes for throw.
Would you say the same for sizeof(unary-expression)?
Bullet points end variously with '.' ',' and no punctuation.
| 4.4 and 4.7
These are very similar points and might be combined.
[For brevity, I don't quote them here.]
| 7.15 Comment out code using `` #if 0…#endif'', or ``//'', not
[My browser doesn't handle – either, but I think your HTML is OK.]
Under these guidelines, are '/*...*/' comments ever OK? If so, when?
| 8.7. Re-use the keywords ``public'', ``private'', and ``protected''
liberally to separate groups of member functions.
The example illustrates this:
class foobar : public foo, public foobaz
public: // constructors, other public interface, etc.
public: // interface required by base class foo
std::auto_ptr<foo> clone() const;
Perhaps a rationale could be supplied, since (to me at least) repeating
'public:' doesn't seem to be the most common practice.
| 10.5. Implementation notes appear separately from public interface and
derivation interface documentation, preferably not in the header file.
Then where should this documentation appear? I'd guess implementation
notes belong in the .?pp file that holds the implementation. For class
templates implemented in a header, that would be the header file. Is
that right? Or do you mean some other file than .cpp or .hpp ?
| 11.3 When std::auto_ is inappropriate
Is 'std::auto_ptr' intended?
| 11.4. Use assert() liberally
Is 'assert()' here shorthand for 'some assertion macro or template'
including BOOST_STATIC_ASSERT or Assert in C++PL3 section 126.96.36.199?
Or does this imply that the macro in <cassert> is to be preferred?
| 11.13 the exception-specification should be generated by a standard
macro (e.g. ALTRA_NO_THROW)
Does this conflict with 2.9? ("Avoid trademarks in names (including
| 14.2-3 ['explicit' keyword; conversion operators]
These items repeat 8.2 and say it better IMO; consider combining or
linking 8.2 with these items.
| 14.6 `C'-style casts are safer than reinterpret_cast<>.
reinterpret_cast can't cast away constness, but a C-style cast can
compose reinterpret_cast and const_cast in one operation. In that
instance I'd call the C-style cast less safe. In what sense would
it be safer?
Does this guideline mean that reinterpret_cast should never be used?
It has the advantage of looking ugly and being easy to grep for.
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk