-
Notifications
You must be signed in to change notification settings - Fork 2
/
HACKING
89 lines (63 loc) · 2.87 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
* Don't commit directly, instead make a pull request on GitHub.
Building from git
-----------------
Before running ./configure in a fresh git checkout, run:
./autogen.sh
Working in libenchant
---------------------
When writing libenchant our priorities are
1) Portable
2) Maintainable & Documented
3) Modular and well designed
When you submit code for inclusion in libenchant, please keep those
things in mind. While performance is important please note that
well-designed algorithms and data structures are fertile areas for
development; obfuscated code to make a loop 3% faster is not. Specifically,
this means:
- Clarity of design and function are paramount
- Make sure your code does not generate warnings
- Please follow the formatting style
Formatting style
----------------
The formatting style of libenchant is a mix of various styles. Please
familiarise yourself with the GNU coding standards (shipped with most
GNU/Linux systems as the standards.info file), then read the Linux
kernel coding standards and ignore Linus's jokes. Then look at the
Gtk+ header files to get acquainted with how to write nice header files
that are almost self documenting.
Emacs users should use the supplied .dir-locals.el.
Remember: Use tabs for indentation: that will keep your
code honest as you will be forced to split your routines into more
modular chunks (as detailed by Linus).
On top of that, please:
- Follow the Gtk+ cleanliness conventions for function
prototypes.
- Follow the Gtk+ namespace convention for function names:
module_submodule_operation
- Every entry point to a public routine should use the
g_return_if_fail and g_return_val_if_fail macros to verify
that the parameters passed are valid.
- Under no circumstances use magic variables. Use typedef
enum { ... } type; to create enumerations. Do not use
integers to hold enumeration values: the compiler can help
catch various errors.
- Use g_warning to mark spots that need to be reviewed or are
not finished.
- Do not submit code that is just a temporary workaround for a
full fledged feature. We do not want to maintain limited
features. It is better to submit an implementation designed
to be expanded and enhanced, even if it is not completely
finished.
- Follow the libenchant commenting style, which is not the Gtk
style;
/* ie. use this for
* multi-line comments
*/
All of this is to ensure the libenchant code will be kept within
reasonable margins of maintainability for the future: Remember, in two years
you will probably be far too busy to maintain your own contributions, and they
might become a burden to the program maintainers.
libenchant is intended to be a foundation for a various document-centric
projects.
Cleaning code in libenchant is more important than trying not to break
existing code. Code clean-ups are always welcome.