git.maemo.org Git - modest/blob - HACKING

   1 HACKING
   2 =======
   3
   4 [ Unfortunately, modest is not following these rules everywhere;
   5 however, it *should* ]
   6
   7 When hacking on modest, please honour these time-tested coding guidelines.
   8 First, please follow the Linux CodingStyle guidelines
   9 (/usr/src/linux/Documentation/CodingStyle); for naming, follow the
  10 Gtk/GObject guidelines.
  11
  12 Here are some additional notes.
  13
  14 Your editor may help you with this, for example for emacs:
  15
  16         (c-set-style "K&R")
  17         (setq tab-width 8)
  18         (setq indent-tabs-mode t)
  19         (setq c-basic-offset 8)
  20
  21 Or the equivalent for your favourite editor.
  22
  23 Lines must not exceed 100 characters.
  24
  25 Functions should do one thing, and do it well. In general, functions
  26 should not be much longer than 20-30 lines (except for, say, handling
  27 many different cases in a 'switch'-statement). Files should not get to
  28 big either; if there are more than, say,1000 lines, it's a sign that
  29 some refactoring should take place.
  30
  31 Code should compile cleanly with gcc's -Wall compile option. Of course this
  32 might not always be possible due to problems in dependent libraries and/or
  33 compiler version. Therefore, do not include -Werror in the standard compile
  34 options; but do use it when building / testing things yourself.
  35
  36 Code should also run cleanly. GTK+/GLib warnings and errors must be
  37 taken very seriously.
  38
  39 Global functions (the ones in .h-files) must be commented using the gtk-doc
  40 system. This way, we generate nice documentation. After installing
  41 (under /usr/local), we can browse the results with DevHelp. Just
  42 add /usr/local/share/gtk-doc/html to the DEVHELP_SEARCH_PATH-environment variable.
  43
  44 g_signal callback function start with 'on_', ie. for a signal "foo-actived",
  45 the corresponding callback function will be called on_foo activated. (if
  46 needed, an namespace prefixes)
  47
  48 global (non-static) functions check their arguments with g_return_if_fail/
  49 g_return_val if_fail. This will give runtime warnings, and point to bugs in
  50 the code. Non-bug problems however, should be reported with g_printerr.
  51        g_printerr ("modest: cannot find icon\n")
  52
  53 Furthermore, please follow 'conventional wisdom' for programming with
  54 GLib/GTK+/GObject. Some things to remember:
  55
  56 * g_new, g_malloc and friends never return NULL. They terminate
  57   the application if it happens (normally).  Therefore, no need to check
  58   for NULL returns;
  59 * g_return_if_fail, g_return_if_reached and friends may be 'turned off',
  60   ie. they are to be used for error checking,  but not for your programming logic
  61
  62
  63 DEBUGGING
  64 =========
  65 There are some DBUS methods available for debugging.
  66
  67 run-standalone.sh  dbus-send --print-reply --dest=com.nokia.modest /com/nokia/modest com.nokia.modest.DumpOperationQueue
  68
  69 (instead of DumpOperationQueue, you can also use DumpSendQueues or
  70 DumpAccounts)
  71
  72 These methods will print a list of the current mail operation queue,
  73 send queues or the accounts. If you don't know what that means, then
  74 this problably not for you :)
  75