_________________________________________________________________

                             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