|
Naming&Coding designDillo's code is divided into modules. For instance: bookmark, cache, dicache, gif. Lets think of a module named "menu", then:
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? 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. You can use:
Function commenting: Every single function of the module should start with a short comment that explains it's purpose; three lines should be enough, but if you think it requires more, enlarge it.
/*
* Try finding the url in the cache. If it hits, send contents
* from there. 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. 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; Function length: Let's try to keep functions within the 45 lines boundary. This eases code reading, following, undestanding 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 g_return_if_fail() at its head. Glib functions:
What do we get with this?
Naming&Coding design by Jorge Arellano Cid |
||||||||||||||||||||||||