Namespaces, file names,...

classic Classic list List threaded Threaded
18 messages Options
Reply | Threaded
Open this post in threaded view
|

Namespaces, file names,...

Geert Janssens
This topic was lightly touched in the doxygen/design thread currently active on this list. I
thought it to be important enough to start a new thread on it.

Historically, gnucash as acquired a lot of namespaces (think function and type prefixes) for
various reasons.

Some examples:
* The oldest engine code uses xaccXYZ because gnucash started as a continuation of the xacc
project (xacc for X Accounting by the way).
* More recent engine code and most of the gui related code usually use gnc_ copying the gtk
name space standards.
* The qof library introduced qof_ because it was meant to become a separate library at one
point in time.

Types are different still:
* The oldest engine code doesn't use prefixes at all ("Split", "Transaction",...)
* More recent engine code uses Gnc or GNC, gui code is mostly into Gnc as well.

And so on...


The problem with this is that it makes the gnucash "framework" hard to learn. It's not possible
to learn by similarity like it is in strongly namespaced frameworks such as gtk, qt or boost.
Those frameworks have a logic to their name structure, so if you know one part of the
framework you can already imagine what other functions and types in the framework will be
called. That speeds up adoption a lot.

The same goes for file names, and especially header files. If there is a recognizable logic in the
names of the header files, that makes it much faster to learn how to use the framework.

Now since one of our current design goals is to port our engine code to C++, that means we will
more or less rewrite every single function and type in it. That would IMO be a good time to think
about how we want to structure the new classes name-wise and come to a more coherent set
of names.

I have seen how some frameworks do it and clearly there are different ways. I don't know
however whether there exist formal theories or guidelines that we could use to formulate our
own naming rules.

For example, in recent years I have worked mostly with the GLib/Gtk frameworks. Some of their
naming rules include
* Object names are prefixed with G (for GLib) and Gtk (for Gtk). The names are camel-cased.
* Function names are prefixed with g_ (for GLib) and gtk_ (for Gtk). An the names use _ to
separate words.

If we had planned to continue to use GLib/Gtk in the long term, I would have proposed to use a
similar naming scheme, using our own Gnc/gnc_ prefixes. That would allow newcomers to
leverage the muscle memory built up on GLib and Gtk naming.

The plan is however to move away from those in favour of C++ based alternatives, so I think it
would make more sense to look for examples of namespacing in the C++ world. That world is
unknown to me unfortunately so...

Suggestions anyone ?

Geert
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Namespaces, file names,...

John Ralls-2

On Sep 5, 2014, at 2:46 AM, Geert Janssens <[hidden email]> wrote:

> This topic was lightly touched in the doxygen/design thread currently active on this list. I
> thought it to be important enough to start a new thread on it.
>
> Historically, gnucash as acquired a lot of namespaces (think function and type prefixes) for
> various reasons.
>
> Some examples:
> * The oldest engine code uses xaccXYZ because gnucash started as a continuation of the xacc
> project (xacc for X Accounting by the way).
> * More recent engine code and most of the gui related code usually use gnc_ copying the gtk
> name space standards.
> * The qof library introduced qof_ because it was meant to become a separate library at one
> point in time.
>
> Types are different still:
> * The oldest engine code doesn't use prefixes at all ("Split", "Transaction",...)
> * More recent engine code uses Gnc or GNC, gui code is mostly into Gnc as well.
>
> And so on...
>
>
> The problem with this is that it makes the gnucash "framework" hard to learn. It's not possible
> to learn by similarity like it is in strongly namespaced frameworks such as gtk, qt or boost.
> Those frameworks have a logic to their name structure, so if you know one part of the
> framework you can already imagine what other functions and types in the framework will be
> called. That speeds up adoption a lot.
>
> The same goes for file names, and especially header files. If there is a recognizable logic in the
> names of the header files, that makes it much faster to learn how to use the framework.
>
> Now since one of our current design goals is to port our engine code to C++, that means we will
> more or less rewrite every single function and type in it. That would IMO be a good time to think
> about how we want to structure the new classes name-wise and come to a more coherent set
> of names.
>
> I have seen how some frameworks do it and clearly there are different ways. I don't know
> however whether there exist formal theories or guidelines that we could use to formulate our
> own naming rules.
>
> For example, in recent years I have worked mostly with the GLib/Gtk frameworks. Some of their
> naming rules include
> * Object names are prefixed with G (for GLib) and Gtk (for Gtk). The names are camel-cased.
> * Function names are prefixed with g_ (for GLib) and gtk_ (for Gtk). An the names use _ to
> separate words.
>
> If we had planned to continue to use GLib/Gtk in the long term, I would have proposed to use a
> similar naming scheme, using our own Gnc/gnc_ prefixes. That would allow newcomers to
> leverage the muscle memory built up on GLib and Gtk naming.
>
> The plan is however to move away from those in favour of C++ based alternatives, so I think it
> would make more sense to look for examples of namespacing in the C++ world. That world is
> unknown to me unfortunately so...
>
> Suggestions anyone ?

C++ actually has a higher level of code scope called namespaces. In behavior it's similar to Python's module naming scheme, and the idea is that it helps to prevent name collisions. I'll leave it to your favorite C++ tutorial/reference to explain further.

Gnome, being dedicated to creating a pretend C++ with C macros, doesn't have the option of enforcing actual namespaces, so they adopted a naming convention and called part of it namespace. Macros being inherently brittle, anything that doesn't comply with that naming convention breaks, though not at compile time and not with a message. There's another reason for the Gnome naming convention: In order to preserve using normal C semantics and because C can't fake the first function argument, all function names must begin with the class name and the first argument must be cast appropriately if it's a derived class. While there's support for vtables (defined in the class_init function), it's not often used outside of Gdk because few C programmers understand it.

We're freed from that with C++. There's no need to stick "GNC" (in any case variation you like) in front of class names, and member functions are automatically recognized and the object parameter taken care of, so instead of
  Account *acct = xaccMallocAccount (book);
  xaccAccountBeginEdit (acct);
  //Do stuff
  xaccAccountCommitEdit (acct);

We'll say
   Account* acct = new Account (book);
   acct->beginEdit (); //or acct->begin_edit (); if we decide we like underscore better than camel case
   //Do stuff
   acct->commitEdit ();

Since we want to make the API useful outside of GnuCash we should declare a namespace to wrap everything in, maybe Gnc. That way an application that wants to extend our Account class could still call their child class Account, like so:
  class Account : public Gnc::Account;
We'd stick
  using namespace Gnc;
in all of our implementation files so we don't have to write
  Gnc::Account* acct = new Gnc::Account (book);

So the question becomes:
* Is Gnc OK for the namespace name?
* Do we want to use camel-case or underscore-separated function and variable names?

N.B. The C++ code above mirrors the old C code to emphasize the different naming and calling conventions. The actual C++ code will be somewhat different.

Regards,
John Ralls


_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Namespaces, file names,...

Buddha Buck
On Fri, Sep 5, 2014 at 11:08 AM, John Ralls <[hidden email]> wrote:

> So the question becomes:
> * Is Gnc OK for the namespace name?
> * Do we want to use camel-case or underscore-separated function and
> variable names?
>
> N.B. The C++ code above mirrors the old C code to emphasize the different
> naming and calling conventions. The actual C++ code will be somewhat
> different.
>

When every method name has to be Hungarian-notated to work with
pseudonamespaces, short namespace abbreviations make sense.

But with true namespaces, using directives, and namespace aliasing
available in C++, I see benefits in readability to use full length names
for namespaces (like GnuCash::Account instead of gncAccount or
Gnc::Account. There's less likelyhood of collision with, say, a library
written to support the General Nutrition Centers (GNC) chain of stores.

While I personally prefer snake_case to camelCase, I think that the
idiomatic C++ tends to use camelCase.
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Namespaces, file names,...

Mike Alexander
On Sep 5, 2014, at 11:26 AM, Buddha Buck <[hidden email]> wrote:

>
> When every method name has to be Hungarian-notated to work with
> pseudonamespaces, short namespace abbreviations make sense.
>
> But with true namespaces, using directives, and namespace aliasing
> available in C++, I see benefits in readability to use full length names
> for namespaces (like GnuCash::Account instead of gncAccount or
> Gnc::Account. There's less likelyhood of collision with, say, a library
> written to support the General Nutrition Centers (GNC) chain of stores.
>
> While I personally prefer snake_case to camelCase, I think that the
> idiomatic C++ tends to use camelCase.

I agree with both points.  I think the namespace name should be spelled out in full and camel case is more often used in C++.  I happen to prefer it, but perhaps that’s just because I’ve used it more.

        Mike
 
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Namespaces, file names,...

John Ralls-2

On Sep 5, 2014, at 10:02 AM, Mike Alexander <[hidden email]> wrote:

> On Sep 5, 2014, at 11:26 AM, Buddha Buck <[hidden email]> wrote:
>>
>> When every method name has to be Hungarian-notated to work with
>> pseudonamespaces, short namespace abbreviations make sense.
>>
>> But with true namespaces, using directives, and namespace aliasing
>> available in C++, I see benefits in readability to use full length names
>> for namespaces (like GnuCash::Account instead of gncAccount or
>> Gnc::Account. There's less likelyhood of collision with, say, a library
>> written to support the General Nutrition Centers (GNC) chain of stores.
>>
>> While I personally prefer snake_case to camelCase, I think that the
>> idiomatic C++ tends to use camelCase.
>
> I agree with both points.  I think the namespace name should be spelled out in full and camel case is more often used in C++.  I happen to prefer it, but perhaps that’s just because I’ve used it more.
>

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.

Regards,
John Ralls
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Namespaces, file names,...

Geert Janssens
On Friday 05 September 2014 12:13:49 John Ralls wrote:

> On Sep 5, 2014, at 10:02 AM, Mike Alexander <[hidden email]> wrote:
> > On Sep 5, 2014, at 11:26 AM, Buddha Buck <[hidden email]> wrote:
> >> When every method name has to be Hungarian-notated to work with
> >> pseudonamespaces, short namespace abbreviations make sense.
> >>
> >> But with true namespaces, using directives, and namespace aliasing
> >> available in C++, I see benefits in readability to use full length
> >> names for namespaces (like GnuCash::Account instead of gncAccount
> >> or Gnc::Account. There's less likelyhood of collision with, say, a
> >> library written to support the General Nutrition Centers (GNC)
> >> chain of stores.
> >>
> >> While I personally prefer snake_case to camelCase, I think that the
> >> idiomatic C++ tends to use camelCase.
> >
> > I agree with both points.  I think the namespace name should be
> > spelled out in full and camel case is more often used in C++.  I
> > happen to prefer it, but perhaps that’s just because I’ve used it
> > more.
> 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.

Apparently lots of schemes exist.
boost uses underscores.

Qt uses camel and goes even further: class types start with a capital letter and each word is
capitalized,  while for member functions each word is capitalized except for the first one.

I also found the naming rules for Google which is a mixture of both:
http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml#General_Naming_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.

Geert
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Namespaces, file names,...

John Ralls-2

On Sep 6, 2014, at 2:06 AM, Geert Janssens <[hidden email]> wrote:

> On Friday 05 September 2014 12:13:49 John Ralls wrote:
> > On Sep 5, 2014, at 10:02 AM, Mike Alexander <[hidden email]> wrote:
> > > On Sep 5, 2014, at 11:26 AM, Buddha Buck <[hidden email]> wrote:
> > >> When every method name has to be Hungarian-notated to work with
> > >> pseudonamespaces, short namespace abbreviations make sense.
> > >>
> > >> But with true namespaces, using directives, and namespace aliasing
> > >> available in C++, I see benefits in readability to use full length
> > >> names for namespaces (like GnuCash::Account instead of gncAccount
> > >> or Gnc::Account. There's less likelyhood of collision with, say, a
> > >> library written to support the General Nutrition Centers (GNC)
> > >> chain of stores.
> > >>
> > >> While I personally prefer snake_case to camelCase, I think that the
> > >> idiomatic C++ tends to use camelCase.
> > >
> > > I agree with both points.  I think the namespace name should be
> > > spelled out in full and camel case is more often used in C++.  I
> > > happen to prefer it, but perhaps that’s just because I’ve used it
> > > more.
> > 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.
>  
> Apparently lots of schemes exist.
> boost uses underscores.
>  
> Qt uses camel and goes even further: class types start with a capital letter and each word is capitalized,  while for member functions each word is capitalized except for the first one.
>  
> I also found the naming rules for Google which is a mixture of both:
> http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml#General_Naming_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 don't. It's immediately apparent what an identifier is from its context: One doesn't call variables or assign to functions. It can be helpful to distinguish member variables from locals and parameters, but that's about it for encoding meaning into identifier names and formats. Consistency and readability are much more important. A lot of style guides argue against abbreviated names on the grounds that they're ambiguous, but I think it's more significant that they're easier to read, though that might hold only if one is fluent in reading the language the identifier is written in. On that vein, anyone want to comment on Stroustrup's claim [1] that snake is easier for non-native-English-speakers to parse?

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.

Regards,
John Ralls

[1] http://www.stroustrup.com/bs_faq2.html#Hungarian

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Namespaces, file names,...

Geert Janssens
On Saturday 06 September 2014 08:09:45 John Ralls wrote:

> On Sep 6, 2014, at 2:06 AM, Geert Janssens <[hidden email]> wrote:
> > On Friday 05 September 2014 12:13:49 John Ralls wrote:
> > > On Sep 5, 2014, at 10:02 AM, Mike Alexander <[hidden email]> wrote:
> > > > On Sep 5, 2014, at 11:26 AM, Buddha Buck <[hidden email]> wrote:
> > > >> When every method name has to be Hungarian-notated to work with
> > > >> pseudonamespaces, short namespace abbreviations make sense.
> > > >>
> > > >> But with true namespaces, using directives, and namespace
> > > >> aliasing
> > > >> available in C++, I see benefits in readability to use full
> > > >> length
> > > >> names for namespaces (like GnuCash::Account instead of
> > > >> gncAccount
> > > >> or Gnc::Account. There's less likelyhood of collision with,
> > > >> say, a
> > > >> library written to support the General Nutrition Centers (GNC)
> > > >> chain of stores.
> > > >>
> > > >> While I personally prefer snake_case to camelCase, I think that
> > > >> the
> > > >> idiomatic C++ tends to use camelCase.
> > > >
> > > > I agree with both points.  I think the namespace name should be
> > > > spelled out in full and camel case is more often used in C++.  I
> > > > happen to prefer it, but perhaps that’s just because I’ve used
> > > > it
> > > > more.
> > >
> > > 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.
> >
> > Apparently lots of schemes exist.
> > boost uses underscores.
> >
> > Qt uses camel and goes even further: class types start with a
> > capital letter and each word is capitalized,  while for member
> > functions each word is capitalized except for the first one.
> >
> > I also found the naming rules for Google which is a mixture of both:
> > http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml#Gener
> > al_Naming_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 don't. It's immediately apparent what an identifier is from its
> context: One doesn't call variables or assign to functions. It can be
> helpful to distinguish member variables from locals and parameters,
> but that's about it for encoding meaning into identifier names and
> formats. Consistency and readability are much more important. A lot
> of style guides argue against abbreviated names on the grounds that
> they're ambiguous, but I think it's more significant that they're
> easier to read, though that might hold only if one is fluent in
> reading the language the identifier is written in. On that vein,
> anyone want to comment on Stroustrup's claim [1] that snake is easier
> for non-native-English-speakers to parse?

I perceive no difference between the two styles. Abbreviations do make it harder to decode
variable or function names. But usually there is sufficient context for me.

>
> 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.
>
As I said, I don't have a strong preference. The point of keeping barriers for entry low is a
valid one. So agreed that we should keep the coding guidelines simple yet effective.

Geert
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Namespaces, file names,...

Christian Stimming-4
In reply to this post by Geert Janssens
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.

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

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.

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

Regards,

Christian

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Namespaces, file names,...

John Ralls-2

On Sep 7, 2014, at 1:09 PM, Christian Stimming <[hidden email]> 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.



_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Namespaces, file names,...

Derek Atkins
In reply to this post by John Ralls-2
John Ralls <[hidden email]> writes:

[snip]

> Since we want to make the API useful outside of GnuCash we should declare a namespace to wrap everything in, maybe Gnc. That way an application that wants to extend our Account class could still call their child class Account, like so:
>   class Account : public Gnc::Account;
> We'd stick
>   using namespace Gnc;
> in all of our implementation files so we don't have to write
>   Gnc::Account* acct = new Gnc::Account (book);
>
> So the question becomes:
> * Is Gnc OK for the namespace name?

Personally I prefer spelled out namespaces, so I would prefer "GnuCash"
instead of "Gnc" or "GNC".

> * Do we want to use camel-case or underscore-separated function and variable names?

My personal preference is CamelCase, where the first letter is capital
for types and classes, and the first letter is lower case for methods.

E.g.:

namespace GnuCash {
  class Account {
    setName(..);
  };
};

As for class members, I do not have a strong opinion about whether or
not to use m_<name>.

Nor do I specifically have a preference about getter/setter names.  I
definitely like setFoo(), but I don't know whether I prefer getFoo() or
foo() as the getter.  I think I have a slight preference to getFoo().

> N.B. The C++ code above mirrors the old C code to emphasize the different naming and calling conventions. The actual C++ code will be somewhat different.
>
> Regards,
> John Ralls

-derek

--
       Derek Atkins, SB '93 MIT EE, SM '95 MIT Media Laboratory
       Member, MIT Student Information Processing Board  (SIPB)
       URL: http://web.mit.edu/warlord/    PP-ASEL-IA     N1NWH
       [hidden email]                        PGP key available
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Namespaces, file names,...

Christian Stimming-4
In reply to this post by John Ralls-2
Am Sonntag, 7. September 2014, 15:10:13 schrieb John Ralls:
> > 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.

I think one relationship wasn't mentioned so far: The filenames and the
corresponding namespace and class names. I think both should be as identical
as possible - similar to Qt, different from glib.

Namespaces in lowercase gives also directory names in lowercase. Class names,
well, should appear in the file names IMHO as unchanged as possible. I prefer
both with the first letter in capital, but I know this causes occasionally
some hassles on windows systems, as those colleagues notoriously forget to add
their include directives with the correct case sensitivity. Other people argue
that file names should be all lowercase in general. Both views exist.

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

Ok for the prefix. However, "static class members" are not at all evil.
They're a normal part of the language and needed for modelling certain aspects
of a program. What is evil are global variables. But static class variables
are just fine - they are fixed into their scope and have access rules. They
are simply needed occasionally. Nothing that necessarily has to be avoided.

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

Ok with me.

Regards,

Christian
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Namespaces, file names,...

John Ralls-2

On Sep 8, 2014, at 11:22 AM, Christian Stimming <[hidden email]> wrote:

> Am Sonntag, 7. September 2014, 15:10:13 schrieb John Ralls:
>>> 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.
>
> I think one relationship wasn't mentioned so far: The filenames and the
> corresponding namespace and class names. I think both should be as identical
> as possible - similar to Qt, different from glib.
>
> Namespaces in lowercase gives also directory names in lowercase. Class names,
> well, should appear in the file names IMHO as unchanged as possible. I prefer
> both with the first letter in capital, but I know this causes occasionally
> some hassles on windows systems, as those colleagues notoriously forget to add
> their include directives with the correct case sensitivity. Other people argue
> that file names should be all lowercase in general. Both views exist.

I agree that filenames should reflect the class that they implement, when they do so, and I’ll add that in general a file should implement only one class. Capitalization is OK as long as one keeps in mind that the Mac file system is normally case-preserving but case-insensitive, so e.g. Account.h and account.h will map to the same file.

I don’t think we want to give each directory its own namespace. I’m not even sure that we want any namespaces inside ‘gnucash’.

>> 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.
>
> Ok for the prefix. However, "static class members" are not at all evil.
> They're a normal part of the language and needed for modelling certain aspects
> of a program. What is evil are global variables. But static class variables
> are just fine - they are fixed into their scope and have access rules. They
> are simply needed occasionally. Nothing that necessarily has to be avoided.

Static member variables, a.k.a. class variables, are indeed a core feature of the language. When using them one just has to be aware that access must be synchronized; fortunately C++11 added some nice sync functions to the standard library that make that reasonably easy. However, synchronization is a bit expensive and so it’s better to avoid it if possible.

There are times when regular member variables need to be synchronized too — any time one has a shared_ptr or naked pointer running around all access to its members must be synchronized.

The same is true of file-scope statics, which aren’t globals, but their existence seldom reflects good C++ design. In general a file-scope static should be a member variable; in some cases a class variable.

Regards,
John Ralls


_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Namespaces, file names,...

Derek Atkins
John Ralls <[hidden email]> writes:

> I agree that filenames should reflect the class that they implement,
> when they do so, and I’ll add that in general a file should implement
> only one class. Capitalization is OK as long as one keeps in mind that
> the Mac file system is normally case-preserving but case-insensitive,
> so e.g. Account.h and account.h will map to the same file.
>
> I don’t think we want to give each directory its own namespace. I’m
> not even sure that we want any namespaces inside ‘gnucash’.

I kind of like the Ruby on Rails method, where the file name is the
lower-case snake form of the class name.  E.g., a class Account would be
in a source file account.[ch], a class ScheduledTransaction would be in
a file scheduled_transaction.[ch], etc.

I agree that we don't need to have a directory for the namespace, and I
also don't think we need to have namespaces for each "module/library".
E.g., I don't think we need GnuCash::Engine::Account.  I suspect doing
so would just add complexity where it might not be warranted.

-derek

--
       Derek Atkins, SB '93 MIT EE, SM '95 MIT Media Laboratory
       Member, MIT Student Information Processing Board  (SIPB)
       URL: http://web.mit.edu/warlord/    PP-ASEL-IA     N1NWH
       [hidden email]                        PGP key available

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Namespaces, file names,...

Christian Stimming-4
Zitat von Derek Atkins <[hidden email]>:

>> I agree that filenames should reflect the class that they implement,
>> when they do so, and I’ll add that in general a file should implement
>> only one class. Capitalization is OK as long as one keeps in mind that
>> the Mac file system is normally case-preserving but case-insensitive,
>> so e.g. Account.h and account.h will map to the same file.
>>
>> I don’t think we want to give each directory its own namespace. I’m
>> not even sure that we want any namespaces inside ‘gnucash’.
>
> I kind of like the Ruby on Rails method, where the file name is the
> lower-case snake form of the class name.  E.g., a class Account would be
> in a source file account.[ch], a class ScheduledTransaction would be in
> a file scheduled_transaction.[ch], etc.

Glib/gtk has a scheme similar to what you mentioned from ruby, just  
with one extra third variation: The typedefs are CamelCase, the file  
names are with the same spelling but all-lowercase, and the function  
names are in snake form.

And: Sorry to object, but I particularly dislike this scheme - it  
means the file names are always different from the class names. Why  
not making them completely identical? In that case, zero thoughts have  
to be spent on how to guess the correct file name for a given class.

> I agree that we don't need to have a directory for the namespace, and I
> also don't think we need to have namespaces for each "module/library".
> E.g., I don't think we need GnuCash::Engine::Account.  I suspect doing
> so would just add complexity where it might not be warranted.

I don't want to vote for extra namespaces, but I'd like to point out  
one technical reason for someone's preferences here: If the preferred  
tool of coding is something cmdline-based or emacs, chances are that  
extra directories mean extra typing work and are rather avoided. If  
the tool of coding is an IDE such as eclipse, qtcreator, or Visual  
Studio, the directories play only a minor role anymore (if visible at  
all in the project view) and chances are that they get to be used more  
often, for grouping of similar things and such. And in C++ (just as in  
java), adding extra namespaces for extra directories can be seen as  
the mapping between the file system and the compiler. In such a  
context, one wants to use gnc::engine::Account, knowing that it  
resides in the header file <gnc/engine/Account.h> on the disk, or  
gnc::backend::xml::XmlFile, knowing that it resides in  
<gnc/backend/xml/XmlFile.h>. You can always get rid of the namespace  
qualifications by using (no pun intended) "using namespace", but I  
know from my own learning curve that multiple namespaces seem rather  
smelly when coming from a C background. After years of C++ I got to  
like them, especially if they are implemented as a direct mapping from  
the directory structure on disk to the class structure in the  
namespaces. But that's just my personal take on this.

Regards,

Christian

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Namespaces, file names,...

John Ralls-2

On Sep 10, 2014, at 4:51 AM, Christian Stimming <[hidden email]> wrote:

> Zitat von Derek Atkins <[hidden email]>:
>
>> I agree that we don't need to have a directory for the namespace, and I
>> also don't think we need to have namespaces for each "module/library".
>> E.g., I don't think we need GnuCash::Engine::Account.  I suspect doing
>> so would just add complexity where it might not be warranted.
>
> I don't want to vote for extra namespaces, but I'd like to point out one technical reason for someone's preferences here: If the preferred tool of coding is something cmdline-based or emacs, chances are that extra directories mean extra typing work and are rather avoided. If the tool of coding is an IDE such as eclipse, qtcreator, or Visual Studio, the directories play only a minor role anymore (if visible at all in the project view) and chances are that they get to be used more often, for grouping of similar things and such. And in C++ (just as in java), adding extra namespaces for extra directories can be seen as the mapping between the file system and the compiler. In such a context, one wants to use gnc::engine::Account, knowing that it resides in the header file <gnc/engine/Account.h> on the disk, or gnc::backend::xml::XmlFile, knowing that it resides in <gnc/backend/xml/XmlFile.h>. You can always get rid of the namespace qualifications by using (no pun intended) "usi!
 ng namespace", but I know from my own learning curve that multiple namespaces seem rather smelly when coming from a C background. After years of C++ I got to like them, especially if they are implemented as a direct mapping from the directory structure on disk to the class structure in the namespaces. But that's just my personal take on this.

That practice of Java is an abomination, and the compiler doesn't need namespaces to map the file system for it. I think you mean build-system anyway: The compiler works on one compilation unit at a time, which consists of the input file plus its includes.

Namespaces exist to isolate identifier names so that they can be reused. The only reason to divide up the GnuCash namespace would be if you envision needing to use the same class name or free-function name in two different contexts. Otherwise it just adds verbosity.

Regards,
John Ralls
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Namespaces, file names,...

Derek Atkins
In reply to this post by Christian Stimming-4
Christian Stimming <[hidden email]> writes:

> Zitat von Derek Atkins <[hidden email]>:
>>> I agree that filenames should reflect the class that they implement,
>>> when they do so, and I’ll add that in general a file should implement
>>> only one class. Capitalization is OK as long as one keeps in mind that
>>> the Mac file system is normally case-preserving but case-insensitive,
>>> so e.g. Account.h and account.h will map to the same file.
>>>
>>> I don’t think we want to give each directory its own namespace. I’m
>>> not even sure that we want any namespaces inside ‘gnucash’.
>>
>> I kind of like the Ruby on Rails method, where the file name is the
>> lower-case snake form of the class name.  E.g., a class Account would be
>> in a source file account.[ch], a class ScheduledTransaction would be in
>> a file scheduled_transaction.[ch], etc.
>
> Glib/gtk has a scheme similar to what you mentioned from ruby, just
> with one extra third variation: The typedefs are CamelCase, the file
> names are with the same spelling but all-lowercase, and the function
> names are in snake form.

Sure, a typedef is effectively a class name.  So yes, I would expect
that to be CamelCase.

> And: Sorry to object, but I particularly dislike this scheme - it
> means the file names are always different from the class names. Why
> not making them completely identical? In that case, zero thoughts have
> to be spent on how to guess the correct file name for a given class.

Two reasons.  First: for file systems that are case-preserving but
case-insensitive, like on Mac and Windows.  In those cases if you do:

  #include "account.h"

It will work regardless of whether the file is account.h or Account.h.
But on Linux, of course, it will only work for the former filename.

I happen to prefer files to be all lower case for consistency.

Second, having a file named "scheduledtransaction.h" is harder to read
than "scheduled_transaction.h", at least IMHO.  Also, if you have
classes that are similar in name except for case you could have a
filename clash.  For example (to use an old joke from SNL):

class Therapists { ... };
class TheRapists { ... };

>> I agree that we don't need to have a directory for the namespace, and I
>> also don't think we need to have namespaces for each "module/library".
>> E.g., I don't think we need GnuCash::Engine::Account.  I suspect doing
>> so would just add complexity where it might not be warranted.
>
> I don't want to vote for extra namespaces, but I'd like to point out
> one technical reason for someone's preferences here: If the preferred
> tool of coding is something cmdline-based or emacs, chances are that
> extra directories mean extra typing work and are rather avoided. If
> the tool of coding is an IDE such as eclipse, qtcreator, or Visual
> Studio, the directories play only a minor role anymore (if visible at
> all in the project view) and chances are that they get to be used more
> often, for grouping of similar things and such. And in C++ (just as in
> java), adding extra namespaces for extra directories can be seen as
> the mapping between the file system and the compiler. In such a
> context, one wants to use gnc::engine::Account, knowing that it
> resides in the header file <gnc/engine/Account.h> on the disk, or
> gnc::backend::xml::XmlFile, knowing that it resides in
> <gnc/backend/xml/XmlFile.h>. You can always get rid of the namespace
> qualifications by using (no pun intended) "using namespace", but I
> know from my own learning curve that multiple namespaces seem rather
> smelly when coming from a C background. After years of C++ I got to
> like them, especially if they are implemented as a direct mapping from
> the directory structure on disk to the class structure in the
> namespaces. But that's just my personal take on this.

True.  For someone not familiar with the code it's nice to be able to
see where in the directory hierarchy a file might live if there is a
direct corellation between the class name and directory structure.

> Regards,
>
> Christian

-derek

--
       Derek Atkins, SB '93 MIT EE, SM '95 MIT Media Laboratory
       Member, MIT Student Information Processing Board  (SIPB)
       URL: http://web.mit.edu/warlord/    PP-ASEL-IA     N1NWH
       [hidden email]                        PGP key available

_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: Namespaces, file names,...

Frank H. Ellenberger-3
I fully agree with Derek.

Frank
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel