Re: [boost] coding guidelines

From: David Abrahams (david.abrahams_at_[hidden])
Date: 2001-07-05 06:53:46

----- Original Message -----
From: "Toon Knapen" <toon_at_[hidden]>
To: <boost_at_[hidden]>
Sent: Thursday, July 05, 2001 6:05 AM
Subject: [boost] coding guidelines

> A few questions
>
> 2.12): Functions describing the state of an object should be English
> noun phrases (e.g. size(), not get_size()).
>
> I neither like the 'get' and 'set' verb before every member functions
> since it clutters the code and makes it longer. But since you also
> suggested to have class names all lowercase you can get into trouble as
> in the next example :
<snip>
> Here the class and the function clash. The problem would be solved by
> saying the classnames should start with a capital letter for instance.

Yes, but the lower-case guideline is just in deference to long-standing
boost and std:: tradition. Usually this is solved by adding _t to the class
name :(.
In practice I've had no trouble with this.

> 7.1):Use ``//'' to delimit comments in lieu of ``/*...*/''
>
> We and many other projects use for instance doxygen for generating
> documentation. Doxygen (and other similar tools) needs the java-style of
> commenting using /** ... */. So could we also allow this in the
> guidelines ? I know, it's a bit awkward to change rules to the protocol
> of some tools but this type of comment has also become quit standard.

Doxygen also responds to ///...
Are /** ... */ really needed for anything?

>
> 8.1,8.6 && 8.7): Class organisation
> As you prefer not to repeat the virtual keyword in derived classes and
> you insist on using 'public:' liberally could we not say that the
> inherited virtual functions need to go in a seperate public: block.
>
> class Base {
>  public:
>     virtual void foo() const = 0;
> };
>
> class Derived : public Base {
>  public:
>     Derived() {};
>  public: // inherited from Base
>     void foo();
> };
>
> This makes it clear which functions are in reality virtual and from
> where they are first declared and documented (as the rule is to document
> the virtual function only in the base class declaration)

This style is strongly suggested by the document; I agree though that it
could be more explicit.

-Dave