Naming&Coding design

Dillo's code is divided into modules. For instance: bookmark, cache, dicache, gif.

Lets think of a module named "menu", then:

• Every internal routine of the module, should start with "Menu_" prefix.
• "Menu_" prefixed functions are not meant to be called from outside the module.
• If the function is to be exported to other modules (i.e. it will be called from the outside), it should be wrapped with an "a_" prefix.

For instance: if the function name is "Menu_create", then it's an internal function, but if we need to call it from the outside, then it should be renamed to "a_Menu_create".

Why the "a_" prefix?

Because it reads better "a_Menu_create" than "d_Menu_create" cause the first one suggests "a Menu create" function!

Another way of understanding this is thinking of "a_" prefixed functions as Dillo's internal library, and the rest ("Menu_" prefixed in our example) as a private module-library.

Indentation: Source code must be indented with 3 blank spaces, no Tabs.
Why?
Because different editors expand or treat tabs in several ways; 8 spaces being the most common, but that makes code really wide and we'll try to keep it within the 80 columns bounds (printer friendly).

You can use:   indent -kr -sc -i3 -bad -nbbo -nut -l79 myfile.c

Function commenting:

Every single function of the module should start with a short comment that explains it's purpose; three lines should be enough, but if you think it requires more, enlarge it.

/*
 * Try finding the url in the cache. If it hits, send contents
 * from there. If it misses, set up a new connection.
 */
int a_Cache_open_url(const char *url, void *Data)
{
   ...
   ...
   ...
}

/* BUG: this counter is not accurate */
++i;

/* todo: get color from the right place */
a = color;

Function length:

Let's try to keep functions within the 45 lines boundary. This eases code reading, following, undestanding and maintenance.

Functions with a single exit:

It's much easier to follow and maintain functions with a single exit point at the bottom (instead of multiple returns). The exception to the rule are calls like g_return_if_fail() at its head.

Glib functions:

• Dillo uses glib extensively. Before starting to code something new, a good starting point is to check what this library has to offer.
• Memory managment must be done using g_new, g_malloc, g_free and their relatives.
• For debugging purposes and error catching (not for normal flow): g_return_if_fail, g_return_val_if_fail, g_warning, etc. are encouraged.
• g_print is extensively used to output additional information to the calling terminal.

What do we get with this?

• A clear module API for Dillo; every function prefixed "a_" is to be used outside the module.
• A way for identifying where the function came from (the capitalized word is the module name).
• An inner ADT (Abstract data type) for the module. That can be isolated, tested and replaced independently.
• A two stage instance for bug-fixing. You can change the exported function algorithms while someone else fixes the internal module-ADT!
• A coding standar ;)

Naming&Coding design by Jorge Arellano Cid