mirror of https://github.com/djcb/mu.git
83 lines
3.0 KiB
Plaintext
83 lines
3.0 KiB
Plaintext
* 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 (C) or 100 characters (C++)
|
|
|
|
3. functions must not exceed 40 lines (there may be rare exceptions), and
|
|
30 lines is already pretty long. You can easily check if any functions
|
|
violate this rule with 'make line33', which lists all functions with
|
|
more than 33 non-comment lines.
|
|
|
|
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.'
|
|
|
|
9. functions have their return type on a separate line before the function
|
|
name, so:
|
|
|
|
int
|
|
foo (const char* bar)
|
|
{
|
|
....
|
|
}
|
|
|
|
|
|
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: ***
|
|
|