emacs
/
mu
mirror of https://github.com/djcb/mu.git
1
0
Fork 0
Code Issues Releases Wiki Activity

Update HACKING

This commit is contained in:
djcb 2014-10-19 18:48:48 +03:00
parent d368c0c3f3
commit 18dcebd820
1 changed files with 64 additions and 55 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

119
HACKING
View File

@ -1,48 +1,52 @@
* HACKING * HACKING
Here are some guidelines for hacking on the 'mu' source code. This is fairly Here are some guidelines for hacking on the 'mu' source code.
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 This is a fairly long list -- this is not meant to discourage anyone
the more stylistic-aesthetic rules are clearly visible in current source code, from working on mu; I think most of the rules are common sense
so as long as any new code 'fits in', it should go a long way in satisfying anyway, and some of the more stylistic-aesthetic rules are clearly
them. 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... I should add some notes for the Lisp/Scheme code as well...
** Coding style ** Coding style
For consistency and, even more important, to keep things understandable, mu For consistency and, more important, to keep things understandable,
attempts to follow the following rules: mu attempts to follow the following rules:
1. basic code layout is like in the Linux kernel coding style, with the '{' 1. Basic code layout is like in the Linux kernel coding style. Keep
on the same line as the statement, except for functions. Tabs/spaces the '{' on the same line as the statement, except for
have width 8. functions. Tabs for indentation, space for aligment; use 8-char
tabs.
2. lines must not exceed 80 characters (C) or 100 characters (C++) 2. Lines should not exceed 80 characters (C) or 100 characters
(C++)
3. functions must not exceed 35 lines. You can easily check if any functions 3. Functions should not exceed 35 lines (with few exceptions). You
violate this rule with 'make line35', which lists all functions with more can easily check if any functions violate this rule with 'make
than 35 non-comment lines. line35', which lists all functions with more than 35 non-comment
lines.
4. source files should not exceed 1000 lines 4. Source files should not exceed 1000 lines
5. a function's cyclomatic complexity should not exceed 10 (there could be 5. A function's cyclomatic complexity should not exceed 10 (there
rare exceptions, see the toplevel Makefile.am). You can test the could be rare exceptions, see the toplevel Makefile.am). You can
cyclomatic complexity with the pmccabe tool; if you installed that, you test the cyclomatic complexity with the pmccabe tool; if you
can use 'make cc10' to list all functions that violate this rule; there installed that, you can use 'make cc10' to list all functions
should be none. that violate this rule; there should be none.
6. filenames have their components separated with dashes (e.g, 'mu-log.h'), 6. Filenames have their components separated with dashes (e.g, 'mu-log.h'),
and start with 'mu-' where appropriate. and start with 'mu-' where appropriate.
7. global functions have the prefix based on their module, e.g., mu-foo.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. 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 8. Non-global functions *don't* have the module prefix, and are declared
static. static.
9. functions have their return type on a separate line before the function 9. Functions have their return type on a separate line before the
name, so: function name, so:
int int
foo (const char *bar) foo (const char *bar)
@ -52,19 +56,19 @@
There is no non-aesthetic reason for this. There is no non-aesthetic reason for this.
10. in C code, variable-declarations are at the beginning of a block; in 10. In C code, variable-declarations are at the beginning of a
principle, C++ follows that same guideline, unless for heavy yet block; in principle, C++ follows that same guideline, unless
uncertain initializations following RAII. for heavy yet uncertain initializations following RAII.
In C code, the declaration does *not* initialize the variable. This will In C code, the declaration does *not* initialize the
give the compiler a chance to warn us if the variable is not initialized variable. This will give the compiler a chance to warn us if
in a certain code path. 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 11. Returned strings of type char* must be freed by the caller; if
not to be freed, 'const char*' should be used instead they are not to be freed, 'const char*' should be used instead
12. functions calls have a space between function name and arguments, unless 12. Functions calls have a space between function name and
there are none, so: arguments, unless there are none, so:
foo (12, 3); foo (12, 3);
@ -74,36 +78,41 @@
after a comma, a space should follow. after a comma, a space should follow.
13. functions that do not take arguments are explicitly declared as f(void) 13. Functions that do not take arguments are explicitly declared as
and not f(). Reason: f() means that the arguments are /unspecified/ (in f(void) and not f(). Reason: f() means that the arguments are
C) /unspecified/ (in C)
14. C-code should use /* comments */, not // commments
** Logging ** Logging
For logging, mu uses the GLib logging functions/macros as listed below, For logging, mu uses the GLib logging functions/macros as listed
except when logging may not have been initialized. below, except when logging may not have been initialized.
The logging system redirects most logging to the log file (typically, The logging system redirects most logging to the log file
~/.mu/mu.log). g_warning, g_message and g_critical are shown to the user, (typically, ~/.mu/mu.log). g_warning, g_message and g_critical are
except when running with --quiet, in which case g_message is *not* shown. 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 - g_message is for non-error messages the user will see (unless
with --quiet) running with --quiet)
- g_warning is for problems the user may be able to do something about (and - g_warning is for problems the user may be able to do something
they are written on stderr) about (and they are written on stderr)
- g_critical is for mu bugs, serious, internal problems (g_return_if_fail and - g_critical is for mu bugs, serious, internal problems
friends use this). (and they are written on stderr) (g_return_if_fail and friends use this). (and they are written on
stderr)
- don't use g_error - don't use g_error
if you just want to log something in the log file without writing to screen, If you just want to log something in the log file without writing
use MU_LOG_WRITE, as defined in mu-util.h to screen, use MU_LOG_WRITE, as defined in mu-util.h
** Compiling from git ** Compiling from git
For hacking, you're strongly advised to use the latest git For hacking, you're strongly advised to use the latest git
version. Compilation from git should be straightforward, if you have the version. Compilation from git should be straightforward, if you
right tools (automake, autoconf and friends) installed -- but if you do have the right tools (automake, autoconf and friends) installed --
development, you'd probably have those. but if you do development, you'd probably have those.
Anyhow, to compile straight from git: Anyhow, to compile straight from git: