diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/NC_design.txt | 91 |
1 files changed, 69 insertions, 22 deletions
diff --git a/doc/NC_design.txt b/doc/NC_design.txt index 6932b9cf..da0b8b46 100644 --- a/doc/NC_design.txt +++ b/doc/NC_design.txt @@ -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) -{ - ... - ... - ... -} - - We also have the BUG: and todo: tags. + /* + * 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; + /* 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. -/* todo: get color from the right place */ -a = color; _________________________________________________________________ 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 |