mirror of https://github.com/djcb/mu.git
122 lines
4.2 KiB
Plaintext
122 lines
4.2 KiB
Plaintext
* HACKING
|
|
|
|
Here are some guidelines for hacking on the 'mu' source code. This is fairly
|
|
long list -- this is not meant to discourage anyone from working on mu; I
|
|
think most of the rules are common sense anyway (or should be), 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
|
|
them.
|
|
|
|
I should add some notes for the Lisp/Scheme code as well...
|
|
|
|
** Coding style
|
|
|
|
For consistency and, even more important, to keep things understandable, mu
|
|
attempts to follow 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 35 lines. You can easily check if any functions
|
|
violate this rule with 'make line35', which lists all functions with more
|
|
than 35 non-comment lines.
|
|
|
|
4. source files should not exceed 1000 lines
|
|
|
|
5. a function's cyclomatic complexity should not exceed 10 (there could be
|
|
rare exceptions, currently there are none in mu). 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'),
|
|
and start with 'mu-' where appropriate.
|
|
|
|
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)
|
|
{
|
|
....
|
|
}
|
|
|
|
There is no non-aesthetic reason for this.
|
|
|
|
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. In C code, the declaration does
|
|
*not* initialize the variable. This will give the compiler a chance to
|
|
warn us if the variable is not initialized in a certain code path.
|
|
|
|
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
|
|
|
|
12. functions calls have a space between function name and arguments, unless
|
|
there are none, so:
|
|
|
|
foo (12, 3);
|
|
|
|
and
|
|
|
|
bar();
|
|
|
|
after a comma, a space should follow.
|
|
|
|
13. functions that do not take arguments are explicitly declared as f(void)
|
|
and not f(). Reason: f() means that the arguments are /unspecified/ (in
|
|
C)
|
|
|
|
** 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 mu bugs, 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 without writing to screen,
|
|
use MU_LOG_WRITE, as defined in mu-util.h
|
|
|
|
** Compiling from git
|
|
|
|
For hacking, you're strongly advised to use the latest git
|
|
version. Compilation from git should be straightforward, if you have the
|
|
right tools (automake, autoconf and friends) installed -- but if you do
|
|
development, you'd probably have those.
|
|
|
|
Anyhow, to compile straight from git:
|
|
|
|
$ git clone https://github.com/djcb/mu
|
|
$ cd mu
|
|
$ autoreconf -i
|
|
$ ./configure
|
|
$ make
|
|
|
|
|
|
# Local Variables:
|
|
# mode: org; org-startup-folded: nofold
|
|
# End:
|
|
|
|
|
|
|
|
|