Re: [boost] coding guidelines

From: Toon Knapen (toon_at_[hidden])
Date: 2001-07-05 08:23:15

> > 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.
> 
Well I already ran multiple time into this problem. e.g.

class topology;
class mesh {
 public:
    const topology& topology() const;
 private:
    topology topology_;
};

As you already indicated, adding _t looks ugly. The solution I would
suggest it to start user-defined classed with an uppercase. This gives
you a distinction between classes that are in the C++ standard and the
ones defined by your fellow programmers. the lowercase strategy for
member functions is more important as this makes it easier to switch
some C++ standard class with a user-defined class without the user
knowing it. e.g. if one has

typedef std::vector< int > MyContainer;
MyContainer mc;
mc.push_back( 20 );

and wishes to develop some special container for his purposes, he can
redefine MyContainer without the above code will ever need to be changed
(except for the typedef of course)

So my point is starting class-names with uppercase does no harm (is even
usefull) while synching with the STL concerning memberfunctions is still
a good idea.

> > 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?

Yep, but this is for one-liners AFAIK. I'll have to check if this gives
the same results as /** ... */