mu/HACKING

* HACKING

  Here are some 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 the 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; if you installed that, you can use 'make cc10' to list all
      functions that violate this rule; there should be none.

   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 is 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: ***