* HACKING

Here are some short guidelines for hacking on the 'mu' source code. Note, this
is fairly long list. This is not meant to discourage anyone from working on
the mu source code; I think most of the rules are common sense anyway, and
some of the more stylistic-aesthetic rules are clearly visible in current
source code, so as long as any new code 'fits in', it should go a long way in
satisfying these rules. 


** Coding style

   For consistency and even more important, to keep things understandable, mu
   follows the following rules:

   1. basic code layout is like in the Linux kernel coding style, with the '{'
      on the same line as the statement, except for functions. Tabs/spaces
      have width 8.

   2. lines must not exceed 80 characters

   3. functions must not exceed 50 lines (there may be rare exceptions), and
      30 lines is already pretty long.

   4. source files should not exceed 1000 lines

   5. a function's cyclomatic complexity should not exceed 10 (there may be
      rare exceptions). You can test the cyclomatic complexity with the
      pmccabe tool

   6. filenames have their components separated with dashes (e.g, 'mu-log.h')

   7. global functions have the prefix based on their module, e.g., mu-foo.h
      declares a function of 'mu_foo_bar (int a);', mu-foo.c implements this.

   8. non-global functions *don't* have the module prefix, and are declared
      static. Their names may start with '_'

   9. functions have their return type on a separate line before the function
      name

   10. in C code, variable-declarations are at the beginning of a block; in
       principle, C++ follows that same guideline, unless for heavy yet
       uncertain initializations following RAII.

   11. returned strings of type char* must be freed by the caller; if they are
       not to be freed, 'const char*' should be used instead

** Logging
   
   For logging, mu uses the GLib logging functions/macros as listed below,
   except when logging may not have been initialized.

   The logging system redirects most logging to the log file (typically,
   ~/.mu/mu.log). g_warning, g_message and g_critical are shown to the user,
   except when running with --quiet, in which case g_message is *not* shown.

   =g_message= are for non-error messages the user will see (unless running with --quiet)
   =g_warning= is for problems the user may be able to do something about (and
   they are written on stderr)
   =g_critical= is for serious, internal problems (g_return_if_fail and
   friends use this). (and they are written on stderr)

   don't use g_error

   if you just want to log something in the log file, use MU_LOG_WRITE, as
   defined in mu-util.h


#+ Local Variables: ***
#+ mode:org ***
#+ End: ***