_________________________________________________________________
Naming&Coding design
_________________________________________________________________
Dillo's code is divided into modules. For instance: bookmark, cache,
dicache, gif.
Let's 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 of historical reasons.
And "a_Menu_create" reads better than "d_Menu_create" because 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 its purpose; three lines must be enough, but if you
think it requires more, enlarge it.
/*
* Try finding the url in the cache. If it hits, send the contents
* to the caller. If it misses, set up a new connection.
*/
int a_Cache_open_url(const char *url, void *Data)
{
...
...
...
}
We also have the BUG:, TODO:, and WORKAROUND: 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;
/* WORKAROUND: the canonical way of doing it doesn't work yet. */
++a; ++a; ++a;
Function length:
Let's try to keep functions within the 45 lines boundary. This eases
code reading, following, understanding 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 dReturn_if_fail() at its head.
dlib functions:
* Dillo uses dlib extensively in its C sources. Before starting
to code something new, a good starting point is to check what
this library has to offer (check dlib/dlib.h).
* Memory management must be done using dNew, dNew0, dMalloc, dFree
and their relatives.
* For debugging purposes and error catching (not for normal flow):
dReturn_if_fail, dReturn_val_if_fail etc. are encouraged.
* The MSG macro is extensively used to output additional information
to the calling terminal.
_________________________________________________________________
C++
Source code in C++ should follow the same rules with these exceptions:
* Class method names are camel-cased and start with lowercase
e.g. appendInputMultipart
* Classes and types start uppercased
e.g. class DilloHtmlReceiver
* Class methods don't need to prefix its module name
e.g. links->get()
We also try to keep the C++ relatively simple. Dillo does use
inheritance and templates, but that's about all.
_________________________________________________________________
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 to identify 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 standard ;)
_________________________________________________________________
Naming&Coding design by Jorge Arellano Cid