changeset 975:f1c377cb931b

update NC_design from website version
author corvid <corvid@lavabit.com
date Tue, 03 Mar 2009 21:54:40 +0000
parents cfd5d7845bf3
children 80e2f488a523
files doc/NC_design.txt
diffstat 1 files changed, 68 insertions(+), 21 deletions(-) [+]
line wrap: on
line diff
--- a/doc/NC_design.txt	Tue Mar 03 20:17:39 2009 +0000
+++ b/doc/NC_design.txt	Tue Mar 03 21:54:40 2009 +0000
@@ -7,7 +7,7 @@
    Dillo's code is divided into modules. For instance: bookmark, cache,
    dicache, gif.
    
-   Lets think of a module named "menu", then:
+   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
@@ -22,54 +22,101 @@
    
    Why the "a_" prefix?
    Because of historical reasons.
-   And it reads better "a_Menu_create" than "d_Menu_create" cause the
+   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.
+   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 must be enough, but if you
+   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)
-{
-   ...
-   ...
-   ...
-}
+   /*
+    * 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: and todo: tags.
+   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;
+   /* BUG: this counter is not accurate */
+   ++i;
 
-/* todo: get color from the right place */
-a = color;
+   /* 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 for identifying where the function came from (the
+     * 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
+     * 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