Programming Guidelines

XFC uses the GNU C++ coding style, except for the following conventions:

• Function and variable names are in lower case with words separated by an underscore.
• Private member variable names have a trailing underscore when a naming conflict arises with a function variable.
• Member function names use the GTK+ function name but without the library prefix or struct type, e.g. get_window() instead of gtk_widget_get_window().
• XFC data types are named with each word capitalized, as in RadioMenuItem, ScrolledWindow and Widget.
• C++ data types such as int, unsigned int and char are used instead of their corresponding GLib typedefs, gint, guint and gchar.
• Dereference operator (*) is associated with the variable name not the type name, i.e. (Widget  *widget) instead of (Widget*  widget).
• Namespace and template indentation is kept to a minimum to preserve horizontal space in header files.

References and Pointers

There are two ways to pass an argument to a function, call-by-value and call-by-reference. Call-by-value copies an argument into the function parameter; modifying the parameter will have no affect on the argument. This is the default in both C and C++. Call-by-reference copies the address of an argument into the function parameter, not the argument; any modifications made to the parameter will affect the argument. In C you call-by-reference when you pass a pointer as an argument to a function. In C++ there are two ways to call-by-reference; you can either pass a pointer or a reference as an argument to a function. If it helps, you can think of a reference as behaving like a constant pointer but using a different notation and with several restrictions. A reference is declared by preceding the parameter name with the & operator, as in Gtk::Widget& widget. In contrast to pointers, XFC associates the & with the type name not the variable name.

The restrictions on the use references are:

• You must initialize a reference, either at its point of declaration or in a constructor's initializer list if it is a class member.
• No operator operates on a reference.  Operators operate on the object the reference refers to.
• You cannot reference a reference.
• You cannot create arrays of references.
• You cannot create a pointer to a reference.
• References are not allowed on bit fields.
• You don't use the & operator when passing an object as a reference.
• You don't use the dereference (*) operator when using a reference. You use a reference as if it were the object being referred to.

Function parameters and return values

References and pointers are an integral part of C++ and XFC uses them frequently for specifying function parameters and return values. A non-copyable object is passed as a pointer if null is a valid value for the call-by-reference function parameter. If null is not a valid value the object is passed by reference. Copyable values such as built-in types, strings and vectors are passed as a const reference and returned by value.

Signal classes are the only exception to this rule; their constructors take a pointer which cannot not be null. A reference is not used because it would conflict with the object class copy constructor.

---