Tinymail type naming scheme and some development rules

[Philip Van Hoof <spam pvanhoof be>]

I'll repeat the naming scheme of this moment (and once it's set in
stone, this will go on a wiki page of the development site):

At this moment are the platform-specific libraries in conflict with
these rules. This will of course be fixed piece by piece.


Reference counting
------------------

o. All methods that return a tinymail type add a reference to the
returned value. If it's the first reference (the method constructs an
instance of the type), the reference count starts at one.

o. Internally it's possible that a reference is added when passing a
tinymail type to another tinymail component. But when the method
returns, or those references must be removed or must be removed in a
near future (near future after the method returned) or must be removed
in a known and documented future.

o. Lists are an example of the above rule. They unreference their
containing instances upon their own destruction once. Adding an item to
a list therefore adds one to the reference count of the item. Which will
be removed or when the list destroys, or when the item gets removed from
the list.

o. List iterators are an example of the first rule: when they return the
current value, they add a reference to the item being returned. Bringing
the reference count of the item to the minimum value of two. When the
list gets destroyed, the reference count of that item will become one
(as the destructor of the list unreferenced the item once). The caller
of the current method of a list iterator is responsible for removing a
reference count addition.

o. The gtk_tree_model_get method in combination with a _INSTANCE_COLUMN
always adds a reference to the instance given to the caller of the
method. The caller must therefore loose that reference just like as if
the instance was returned.

o. Reparenting happens outside of a component. This means that the
component adds its reference while the injector is responsible for
removing its own reference (or the type-constructors reference).

o. For people who have no clue about how GObject works: when the
reference count of an instance reached zero, the instance is destroyed.
When an instance is constructed, its reference count is set as one.

o. The bindings for programming languages that use Garbage Collection,
should care (or at least know) about the reference counting of the
tinymail types. If they fuck things up, strange things will happen and
other things will not work as expected.


All types:
----------
o. All types are prefixed by "Tny", "TNY_" and "tny_"

Interfaces:
-----------
o. Interfaces have the infamous "Iface", "_IFACE" and "_iface" suffix
o. The naming rules for interfaces might be changed soon (the IFACE
suffix might be removed)

Classes
-------
o. Classes have a implementation-detail prefix after the "Tny", "TNY_"
and "tny_" prefix: TnyCamelType, TnyGtkType, TnyOLPCType, TnyGPEType,
TnyMaemoType

o. Cause of this first rule, it can't be possible to have a name
conflict with the interface.

o. Classes implement an interface. Classes therefore get their API from
their corresponding interface. Classes typically don't create new API
unless the API is specific to the implementation itself.

In case a lot API is added by a class, it's probably time to refactor
the type API of the interface to enforce support for the added
functionality in all types that implement the interface.

o. Concrete classes have a constructor that returns the interface type.

o. Abstract classes don't have a constructor

o. Virtual methods of a class are represented by an over-writable
function pointer in the GObject class-struct of the class. This means
that the default implementation must follow that function pointer to an
implementation method. That the initialization of the abstract class
must, in case there's a default implementation, set that function
pointer itself too.

o. In case there's no default implementation for any of the virtual
methods, there can also be be no constructor for the type. Because this
basically means that the class is an abstract class.

o. Overriding an abstract class and implementing (some of) its virtual
methods means overriding the function pointers of the abstract classes
class-struct in the GObject initialization of the type that implements.

Enums
-----

o. Enums are represented by a GType (g_enum_register_static). Enums
carry the name of the type which uses the enums or carries a name that
makes it very obvious what the enum is to be used for.

o. Enums are freely suffixed. It's recommended to suffix a prefix with
the following patterns:
    o. "Column" in case it's an enum for a GtkTreeModelColumn
    o. "Option" in case it's an option
    o. "Options" or "Flags" in case it's a OR-able flag
    o. "Type" in case the enum is about a type
    o. "Types" in case the enum can represent multiple types (OR-ed)

o. All public enums are represented by a #define label like the typical
TYPE label also seen in GObject classes. It returns the GType get_type
method of the enum. This makes creating language bindings more easy.


o. Structs
----------

o. Public structs "always" have a forward typedef and always start with
an underscore. The forward typedef removes the underscore. This method
works best with IDE's, ctags and C++ compilers and has become some sort
of standard in GObject libraries.

Other simple types
------------------
o. Always use the glib type if there is one (gsize, gint, gchar)
o. "const" followed by a simple type means that it's read-only
o. "const" followed by a "gchar*" (char pointer) means that it's a
read-only string that is handled internally (for example cached) and
therefore shouldn't be freed by the caller.
o. Be architecture safe (don't mix int32 with int64 and pointers)
o. A void pointer is done using the gpointer type. Not your own
invention (definitely not a int32* but also not a void*).
o. #pragma pack(x) is used with care and must be tested on all supported
architectures before enabled on a struct


-- 
Philip Van Hoof, software developer at x-tend 
home: me at pvanhoof dot be 
gnome: pvanhoof at gnome dot org 
work: vanhoof at x-tend dot be 
http://www.pvanhoof.be - http://www.x-tend.be