forked from Chris00/mu
-
Notifications
You must be signed in to change notification settings - Fork 0
/
HACKING
148 lines (103 loc) · 4.82 KB
/
HACKING
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
* HACKING
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, 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. Keep
the '{' on the same line as the statement, except for
functions. Tabs for indentation, space for aligment; use 8-char
tabs.
2. Lines should not exceed 80 characters (C) or 100 characters
(C++)
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
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'),
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)
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.
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 installed.
*** dependencies
You need to install a few dependencies; e.g. on Debian/Ubuntu:
sudo apt-get install \
automake \
autoconf-archive \
autotools-dev \
libglib2.0-dev \
libxapian-dev \
libgmime-2.6-dev \
m4 \
make \
libtool \
pkg-config
Then, to compile straight from git:
$ git clone https://github.com/djcb/mu
$ cd mu
$ ./autogen.sh
$ make
You only need to run ./autogen.sh the first time and after changes
in the build system; otherwise you can use ./configure.
# Local Variables:
# mode: org; org-startup-folded: nofold
# End: