Interesting note on coding standards

*JDH The only thing that I *really dislike about Sun's standard is that they don't differentiate member variables from local variables. There are other things I miss (like my very own flavor of "antiquated Hungarian notation") - but it's that first one that bugs me the most!

Interesting. I find it useful to use naming conventions to distinguish scope. That's one of the reasons that I think Ruby's use of variable name prefixes is better than Perl's. In languages with compile-time typing, like C++, I dislike the clutter of including the type in the name. In those languages, there are too many types (just telling me something is a 'user-defined types' wouldn't very useful) and the compiler will usually tell me about type mismatches (barring problems due to ill-advised uses of implicit constructors and user-defined conversion operators). I'm pretty consistent in my C++ code these days: 'm_' for member variables, 's_' for static with limited scope (function or file), 'g_' for global, and no prefix for local variables.) I've also seen 'my_' for member variables, 'the_' for globals, and 'our_' for static member variables, which is kind of cute because it really is almost readable as English. :-) But neither of these conventions quite covers all the permuations that one might be interested in: local, function static, file static, class static, global. Probably not worth distinguishing all five cases with different prefixes, though, because the subtle variations of static don't matter to most code.

From the Subversion developer's mailing list:

--- Scott Lamb <slamb@slamb.org> wrote:

> Justin Erenkrantz wrote:

> > On Sat, Aug 24, 2002 at 10:10:12AM -0700, Brent R. Matzelle

> wrote:

> > 

> >>To download the API download the source from the RapidSVN

> repository

> >>(under /src/svncpp):
> >>
> >>http://svn.collab.net/repos/svn/clients/rapidsvn/trunk

> > 
> > And, the hungarian notation is, well, antiquated.  Not to mention
> > some of the code formatting is a bit weird (what's up with
> > Status::LoadPath?)

> 
> Okay, since coding style issues have been mentioned and no flamewar
> has 
> resulted, I'm going to be daring. Hopefully this strange magic will
> 
> continue.
> 
> I try to write all my C++ code and doxygen doc comments to adhere
> to 
> Sun's standards, which I find work equally well for C++/doxygen as
> for 
> Javadoc:
> 
> <http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html>
>

<http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#styleguide>

> 
> I think a lot of their decisions are arbitrary, but there are a
> couple 
> big advantages to following these documents:
> 
> - They are well-understood. Anyone who does anything with Java will
> have 
> some intuitive understanding of these, because they see them in all
> the 
> standard API stuff. And lots of people do stuff with Java.
> 
> - They are really thorough, mentioning a lot of things people do 
> inconsistently without a second thought.
> 
> I noticed the SvnCpp stuff isn't following these in at least a
> couple ways:
> 
> - Case issues: Svn::Client::GetError() vs. svn::Client::getError() 
> (Namespaces likethis, classes LikeThis, method names likeThis.) It
> makes 
> it a little bit easier to glance at a name and tell what it is.
> 
> - Grammar conventions for Javadoc: they always use third person.
> The 
> SvnCpp stuff mostly does, but there are a few second-person bits: 
> "Initialize the primary memory pool" vs. "Initializes the primary
> memory 
> pool".
> 
> IMHO it would be worthwhile to switch to their conventions.


I did some research and many major C++ API projects use this
convention.  The class already matches this format with its
documentation and variable naming.  The API has not yet been
implemented in RapidSVN (save one place) so there would not be many
changes.  So after a lot of thought and research I made those
suggested changes.  

Regards,

Brent.