Namespaces, file names,...

[John Ralls]

On Sep 7, 2014, at 1:09 PM, Christian Stimming <christian at cstimming.de> wrote:

> Just for there record, here's my take on potential coding conventions:
> 
> Am Samstag, 6. September 2014, 11:06:13 schrieb Geert Janssens:
>>> Yes, using GnuCash is less ambiguous that Gnc. Sold. For the record I
>>> don’t care about snake vs. camel as long as we pick one.
>> 
>> John, thanks for elaborating on the differences between c and c++ concerning
>> namespaces.
>> 
>> I also prefer the namespace name to be GnuCash in full. I don't have a
>> strong preference regarding snake vs. camel either.
> 
> I strongly prefer namespaces in all-lowercase. I have somewhat a preference 
> for "gnc" as namespace name, but we are an application anyway and not a 
> library, so we're basically free to choose whatever we want as interface 
> naming schemes.

Any particular reason for the all lowercase preference? Not that it matters, gnucash and GnuCash are equally unique.

> 
>> Apparently lots of schemes exist.
>> boost uses underscores.
> 
> Yes, boost and also the STL (std::...) uses underscores. For things that we 
> define in analogy to STL, we will probably re-use their underscore scheme also 
> regularly (such as typedef Xyz base_class; and typedef Xyz value_type;) in 
> case we define things that are commonly defined in STL as well.
>> I also found the naming rules for Google which is a mixture of both:
>> http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml#General_Namin
>> g_Rules
>> 
>> The latter takes more discipline while coding. On the other hand it helps
>> distinguish what a word means. Is it a variable, a type a function ? The
>> style it's written in helps distinguish in this case.
>> 
>> Personally I like such a scheme.
> 
> I also like the convention of type/class names starting with a capital. Other 
> than that, I have no strong preference between Camel and snake. Yes, in 
> general I would consider snake slighly easier to read for me as a non-English 
> native speaker, but I've worked with both and the difference is rather a 
> matter of taste.

Yes, it helps to make clear that the class doesn't come from std:: or boost::, as Stroustrup points out in his FAQ. 

> 
> I see some interesting part of a C++ coding convention, besides the general 
> naming scheme of types and varianles:
> - Class member variables? From other projects I would propose a prefix such as 
> "m_", google has a "_" suffix. 
> - Member getters and setters (accessor and mutator methods)? From other 
> projects (and also Java) I would propose a prefix "get" and prefix "set", i.e. 
> getSomeVariable, setSomeVariable; Qt uses no prefix for the getter and "set" 
> for the setter: someVariable, setSomeVariable; google has no prefix for the 
> getter and "set_" for the setter: some_variable, set_some_variable.

Apple's guidelines also use just the name of the member variable for getters and set+variableName for setters.

I don't mind tagging member variables, and I find m_varName to be clearer than just sticking an underscore at the end. One can go one step further and tag static members with a c_ or an s_, while being aware that static members, just like any other static or global variable, require extra synchronization and so should be avoided as much as possible.

> 
>> It's also the case that the longer and more complicated the style guide the
>> less likely it is that it will be followed. That's partly down to self
>> discipline but more to the volunteer nature of open source projects. We
>> don't want to chase away contributors by making them read and follow a
>> 100-page style document.
> 
> That's correct. However, as we (read: you) will create the C++ classes of the 
> gnucash engine types in the near future, we better decide up front whether we 
> want to have those types named with some consistency. In src/optional/gtkmm I 
> used my own preferred convention for the C++ wrapper classes, but when we 
> really define our core types, we probably better decide on our common 
> preferences. Hence, this discussion is not so much for a large style guide of 
> the majority of our future code, but rather for good standarization elements 
> when defining those commonly used types for ourselves.

Yup.

Only Mike has expressed a strong preference for camel, with everyone else not seeming to care much. So let's go with camel, with Typenames (classes, structs, enums, and POD aliases) having the first word capitalized and function and variable names having the first word lower case. Functions with 'C' linkage (i.e. legacy wrappers for keeping the rest of GnuCash working) will be snake or start with xacc.

Macros, and only macros, will be all caps.

Let's also have the following conventions for "special" variable names:
* Member variables begin with m_
* Static member variables begin with c_ (for class)
* static constants begin with k_ (and should always be used instead of macros)
* static variables in the anonymous namespace (a.k.a. file scope) begin with s_ and require a detailed comment about why such a thing is the only feasible way to implement whatever-it-is.