2 <title>Coding guidelines</title>
4 When hacking on modest, please honour these time-tested coding guidelines.
5 First, please follow the <emphasis>Linux CodingStyle guidelines</emphasis>
6 (<filename>/usr/src/linux/Documentation/CodingStyle</filename>).
10 Here are only some additional notes.
14 Your editor may help you with this, for example for <application>emacs</application>:
16 (c-set-style "K&R")
18 (setq indent-tabs-mode t)
19 (setq c-basic-offset 8)
22 Or the equivalent in your favourite editor.
26 Lines must not exceed 100 characters.
30 Functions should do one thing, and do it well. In general, functions
31 should not be much longer than 20-30 lines (except for, say, handling
32 many different cases in a 'switch'-statement). Files should not get to
33 big either; if there are more than, say, 800 lines, it's a sign that
34 some refactoring should take place.
38 Code should compile cleanly
39 with <command>gcc</command>'s <symbol>-Wall</symbol> compile option. Of
40 course this might not always be possible due to problems in dependent
41 libraries and/or compiler version. Therefore, do not
42 include <symbol>-Werror</symbol> in the standard compile options; but
43 do use it when building / testing things yourself.
47 Code should also run cleanly. GTK+/GLib warnings and errors must be
48 taken very seriously. If you run <application>modest</application> with
49 the <symbol>-d</symbol>-flag, it will <symbol>abort</symbol> whenever
50 there is such a warning. This can be useful when running inside the
54 <para>Global functions (the ones in <filename>.h</filename>-files) must
55 be commented using <systemitem>gtk-doc</systemitem>. This way, we
56 generate nice documentation. After installing
57 (under <filename>/usr/local</filename>), we can browse the results
58 with <application>DevHelp</application>. Just
59 add <systemitem>/usr/local/share/gtk-doc/html</systemitem> to the
60 <systemitem>DEVHELP_SEARCH_PATH</systemitem>-environment variable.
63 Furthermore, please follow 'conventional wisdom' for programming with
64 GLib/GTK+/GObject. Some things to remember:
66 <listitem> <function>g_new</function>, <function>g_malloc</function> and
67 friends <emphasis>never</emphasis> return <function>NULL</function>. They terminate
68 the application if it happens (normally). No need to check
69 for <function>NULL</function> returns;</listitem>
70 <listitem> <function>g_return_if_fail</function> and friends may be
71 'turned off', ie. they are to be used for error checking,
72 but <emphasis>not</emphasis> for your programming logic