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

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)
{
   ...
   ...
   ...
}

We also have the BUG: and todo: tags.
Use them within source code comments to spot hidden issues. For instance:

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

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

What do we get with this?

Naming&Coding design by Jorge Arellano Cid