Revision as of 08:15, 23 November 2011

C Format

Gnucash is fairly relaxed about code format, but we will periodically run a reformatter called Artistic Style (astyle) over the code to clean it up. To reduce the need for this (it messes up VCS history, particularly "blame"), please format your code as follows.

In general, follow the GNU format except use four spaces instead of two for the indents, and don't indent the braces. To summarize, a properly formatted function will look like this:

 guint
 gnc_account_foo (Account *account, gpointer bar)
 {
      Split *baz;
      guint salt;
      if (gnc_split_waldo (baz) > 0)
      {
           salt = gnc_split_pepper (baz);
      }
      return salt;
 }

Please keep lines under 80 characters. If you need to wrap, line up the function arguments like this:

 gnc_account_function_with_a_lot_of_paramters (LongTypeName foo, LongerTypeName *bar,
                                               TypeName baz)
 {
 }

We don't do the wide separation of names and aligned parameters, so don't do this:

 void gnc_account_foo               (Account     *bar,
                                     Split       *baz,
                                     gpointer     waldo);
 Split *gnc_account_pepper          (Account     *salt,
                                     Transaction *sausage);

Instead, do it this way:

 void gnc_account_foo (Account *bar, Split *baz, gpointer waldo);
 Split *gnc_account_pepper (Account *salt, Transaction *sausage);

For the record, the astyle commandline we use (with astyle version 1.24; other versions might result in slightly different formatting) is

 astyle --indent=spaces=4 --brackets=break --pad-oper  *.[hc]

The rationale for the arguments is contained in this email.

Framework

Gnucash is a Gtk+ project. It's design is object-oriented using Gnome's GObject C-language framework.

Remember that even though it's in C, it's supposed to be object-oriented code, so decompose your problem with objects, not procedurally. Try to keep functions short and well named.

Gnucash is also based upon GLib, a very rich foundation library. Familiarize yourself with GLib's many utilities and data types, and use them. In particular do not write a utility for something which GLib already does.

(Yes, in spite of those fine words, there's a lot of code in Gnucash that doesn't use GLib types, duplicates GLib or GObject functionality, or is procedural instead of object oriented. We'll eventually get that refactored out, but in the meantime, don't make it any worse.)

Guile and Scheme

Gnucash is partly implemented in a Scheme dialect called Guile. (It was originally written mostly in Guile, but that implementation was largely replaced with C several years ago.) In particular, the reports system and part of the business system are written in Guile. To support that, most of the core "engine" API is wrapped and accessible from Guile.