HACKING


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67


HACKING
=======

General remarks
---------------

* Code is a maximum of 80 characters wide. This keeps it readable also where
  the original screen width limitations do not apply any more.

* Use C99, in particular stdint and stdbool, except that variables go at the 
  beginning of the block. You may use embedded counters in `for' loops though.

* Do not initialise variables, pointers in particular, where they are declared.
  Initialise immediately before usage and read compiler warnings to find out
  whether any variables are being used without initialisation.

* Use variable names in `sizeof()` statements rather than type names. Otherwise
  refactorings including changing the datatype can render those broken. Example:

    foo_t *f;
    memset (f, 0, sizeof (*f));

* Do not include a `default' case when switching over enumerations, so you'll
  get warnings when a values is added.

* Avoid casts whenever possible - especially with function pointers - as they 
  hinder the compiler's semantic analysis to do its thing.

Including files
---------------

* Always include files in the following order:
    1. C headers, in alphabetical order.
    2. Dependency libraries' headers, in alphabetical order.
    3. Project headers, in alphabetical order.

* In header files only ever include using pointy brackets and directory prefix.
  This makes sure that installed headers work correctly and facilitates 
  installation of multiple incompatible library versions in the same prefix.
  Example foo.h:

    `#include <bar/bar.h>`

  In C files plain inclusion of headers from the project is encouraged, just
  give the header's file name and leave setting of directories to the build
  system. Example foo.c:
  
    `#include "foo.h"`

* In Makefile.am foo_CPPFLAGS always put local include paths before global
  ones, so ambiguous headers are resolved in favour of the local ones.

Making a release
----------------

* NEWS.
* TODO.
* Commit and push.
* `make distcheck`.
* Tag and push.
* Upload tarball.
* Announce.
* Bump version and add extra version in configure.in.
* Commit and push.
* Update web-page.