diff --git a/HACKING b/HACKING index db68163d..fbf5677a 100644 --- a/HACKING +++ b/HACKING @@ -1,48 +1,52 @@ * 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. + Here are some guidelines for hacking on the 'mu' source code. + + This is a fairly long list -- this is not meant to discourage anyone + from working on mu; 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 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: + For consistency and, 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. + 1. Basic code layout is like in the Linux kernel coding style. Keep + the '{' on the same line as the statement, except for + 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 - violate this rule with 'make line35', which lists all functions with more - than 35 non-comment lines. + 3. Functions should not exceed 35 lines (with few exceptions). 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 + 4. Source files should not exceed 1000 lines - 5. a function's cyclomatic complexity should not exceed 10 (there could be - rare exceptions, see the toplevel Makefile.am). 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. + 5. A function's cyclomatic complexity should not exceed 10 (there + could be rare exceptions, see the toplevel Makefile.am). 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'), + 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 + 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 + 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: + 9. Functions have their return type on a separate line before the + function name, so: int foo (const char *bar) @@ -52,19 +56,19 @@ 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. + 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. + 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 + 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: + 12. Functions calls have a space between function name and + arguments, unless there are none, so: foo (12, 3); @@ -74,36 +78,41 @@ 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) + 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) + + 14. C-code should use /* comments */, not // commments + ** Logging - For logging, mu uses the GLib logging functions/macros as listed below, - except when logging may not have been initialized. + 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. + 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) + - 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 + 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. + 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: