git.maemo.org Git - modest/blob - docs/reference/modest-coding-guidelines.sgml

   1   <part>
   2     <title>Coding guidelines</title>
   3     <partintro>
   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>).
   7     </partintro>
   8
   9     <para>
  10       Here are only some additional notes.
  11     </para>
  12
  13     <para>
  14       Your editor may help you with this, for example for <application>emacs</application>:
  15       <programlisting>
  16         (c-set-style "K&amp;R")
  17         (setq tab-width 8)
  18         (setq indent-tabs-mode t)
  19         (setq c-basic-offset 8)
  20       </programlisting>
  21
  22       Or the equivalent in your favourite editor.
  23     </para>
  24
  25     <para>
  26       Lines must not exceed 100 characters.
  27     </para>
  28
  29     <para>
  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.
  35     </para>
  36
  37     <para>
  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.
  44     </para>
  45
  46     <para>
  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
  51       debugger.
  52     </para>
  53
  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.
  61     </para>
  62     <para>
  63       Furthermore, please follow 'conventional wisdom' for programming with
  64       GLib/GTK+/GObject. Some things to remember:
  65       <itemizedlist>
  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
  73         </listitem>
  74       </itemizedlist>
  75     </para>
  76   </part>