This is simply a collection of notes about coding stuff to maintain consistency.
A good way to maintain consistency is have the editor do the indenting/commenting etc. If you use the right profile code then there are some emacs functions to do this which include:
The standard for code has been to indent by two for each block, there seems no reason to change it. Line length should be kept to somewhere between 80 and 120 chars, i.e. something that will fit comfortably on to a screen with a reasonable font size. BUT exceeding this length occasionally is not a problem.
int func(void)
{
int some_var ;
if (blah)
{
call_something() ;
}
return ;
}
Block comments and line comments should be in this style:
if (blah)
{
/* This is quite a long block
* comment that runs to more than one
* line. */
call_something() ; /* unknown function */
}
General naming conventions:
Its useful to adopt different naming styles for external interface functions, internal interface functions and static functions:
By convention the first local variable declared in a function should be the return value which should be correctly initialised:
gboolean someFunc(void)
{
gboolean result = FALSE ;
return result ;
}
This helps a lot with scanning the code.
A standard way to test that program state is as you expect while debugging is via the assert macro or variants thereof. One problem with this kind of macro however is that it easily gets used where really the code should detect the error and handle it via a return code, user message or whatever.
The following guidelines should be followed:
"Package" interface functions: must handle errors in the supplied parameters and return error codes when given faulty data.
"Package" internal functions: should use the zMapAssert() macro to test essential inputs and core dump if there are errors.
The philosophy is that packages should "expect" and handle errors in their inputs while functions internal to packages should expect no errors in their essential inputs and should abort when this happens as it indicates a programming error within the package.
Currently ZMap code has not adherred to this philosopy rigidly enough with the result that ZMap crashes in places where it should be handling errors and ultimately logging an error and/or displaying an error to the user.