140 lines
5.0 KiB
Plaintext
140 lines
5.0 KiB
Plaintext
_________________________________________________________________
|
|
|
|
OBSOLETE -- Flenser is moving to C++23
|
|
_________________________________________________________________
|
|
|
|
|
|
Descriptions of organization of where files are and such are still
|
|
somewhat accurate. However, all style and coding rules are hereby
|
|
repealed. Coding whitespace style will follow local norms, until C
|
|
memory management is mostly removed. All structural and process
|
|
rules regarding memory management, etc. are repealed in favour of
|
|
modern C++ best practices.
|
|
|
|
_________________________________________________________________
|
|
|
|
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
|