diff options
Diffstat (limited to 'doc/NC_design.txt')
-rw-r--r-- | doc/NC_design.txt | 127 |
1 files changed, 0 insertions, 127 deletions
diff --git a/doc/NC_design.txt b/doc/NC_design.txt deleted file mode 100644 index 380787f6..00000000 --- a/doc/NC_design.txt +++ /dev/null @@ -1,127 +0,0 @@ - - _________________________________________________________________ - - 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 |