Re: naming convention

From: Beman Dawes (bdawes_at_[hidden])
Date: 2001-12-27 17:22:52

At 02:10 PM 12/27/2001, Paul Beardsley wrote:
 >Hello,
 >
 >I am developing a computer vision geometry-based
 >library and am interested in working to Boost
 >coding conventions.  I looked at the Boost web page,
 >which
 >says that one should adopt the conventions of the
 >standard library, but I did not find an explicit
 >itemization of naming conventions.  I guess
 >that's because these are murky waters where
 >it is not possible to be too explicit, but anyway
 >my questions are -
 >
 >1.  I assume that the following are obvious
 >conventions, for consistency with the standard
 >library - all lowercase names for class methods, with
 >underscore as a word separator; also the use of
 >existing names such as 'clear' and 'empty' if
 >appropriate.  Is there some place where these
 >conventions are listed explicitly?

There is a one sentence description in www.boost.org/more/lib_guide.htm, 
which says:

Use the lowercase/underscore naming conventions of the C++ standard 
library.  Template parameter names begin with an uppercase letter. Macro 
(gasp!) names should be all uppercase and begin with BOOST_.

Other than that, I'm not aware of a real description.  If you'd care to 
write one, we'll add it to the site.

(Hum... What happened to the coding guidelines Dave Abrahams was working 
on?  Do they have anything to say on the subject?)

 >2.  For access methods, many people use 'get', but
 >the standard library does not e.g. it
 >uses 'size' in preference to 'get_size'.  So is it
 >true that 'get' is not used, and in general one
 >uses a method called 'obj' instead of 'get_obj'?

Yes, set_ and get_ name prefixes are generally avoided.  IIRC, they are 
viewed as not adding enough useful information to be worth the clutter.

 >What about using a method naming convention

In C++ speak, say "member function", not "method":-)

 >to distinguish between
 >a class method which returns a reference and one which
 >returns a value on the stack? - e.g.
 >  A a () const;
 >and
 >  const B& b_ref () const;
 >(The purpose of this would be for clarity in the code
 >which invokes these methods).

With C++'s strong type system, the compiler takes care of the issues which 
led to naming conventions in other languages which add type information to 
names.  C++ names can avoid that ugly clutter since the compiler will guard 
against type mismatch problems.

 >3.  A few years ago when I started C++, someone told
 >me about the convention that arguments to class
 >methods or functions are (a) const references for the
 >read-only arguments, and (b) non-const pointers for write
 >arguments.

I think the more usual rule-of-thumb is something like:

(a) read-only arguments: by value for builtin types, otherwise by const 
reference.
(b) arguments written to: by reference

Some people add something like

(c) If a pointer or reference is to be stored for later use, pass it as a 
pointer to emphasize the usage.  If ownership is involved, pass it wrapped 
in some kind of smart pointer.

I expect Scott Meyers Effective C++ / More Effective C++ books would deal 
with the issues in detail.

 >I recently was talking to a Boost member
 >who told me he remembered a discussion in which
 >generally Boost did not like this convention, although
 >he did not recall all the details (I did not
 >find it in the archives).  My question is
 >do Boost developers avoid this convention and why?  I
 >can suggest one strong advantage of it.  In a piece
 >of calling code, like
 >
 >  A a;
 >  B b;
 >  C c;
 >  MyObj::do_something (a, b, &c);
 >
 >I can immediately see that a and b should be already
 >initialised and will be read-only, and c will be
 >written to - in fact, I further design things such
 >that
 >a write argument like 'c', contains no data on entry,

But it might; you have to read the preconditions in the docs to be sure.

 >and it is the responsibility of a method like
 >'do_something' to (a) initialise 'c' if it
 >is successful, or (b) to clear 'c' and return it
 >in empty state if it is not successful.
 >
 >I find that makes reading code like the above
 >pretty unambiguous in terms of the effects of the
 >invoked method.  So if the const-reference/non
 >const-pointer convention is not accepted, why not?

It uglifies the code, yet brings little benefit.  Particularly since modern 
program editors show the argument type while you are typing or inspecting 
the code.

 >4. Are there any other guidelines which make the
 >code look Boost-like?

Look at the draft of Dave Abrahams guidelines.  Maybe he can comment as to 
where to find a recent version.

--Beman