-
Notifications
You must be signed in to change notification settings - Fork 2
/
HACKING
182 lines (130 loc) · 7.05 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
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
Source code repository
======================
gxsm source code is maintained using the git version control system
and is available at the following location:
https://github.com/pyzahl/Gxsm4/
Building from git
=================
git clone https://github.com/pyzahl/Gxsm4 gxsm4-git
cd gxsm4-git
mkdir builddir
meson builddir
ninja
sudo ninja install
You can replace the ninja commands by
cd builddir
meson compile
sudo meson install
Commit guidelines
=================
Please create patches with the git format-patch command.
If you are a translator feel free to mark strings for translation,
fix typos in the code, etc.
Please send patches for build & configure fixes too. I really appreciate
your help, I just want to review these fixes before applying.
If you are a "build sheriff", feel free to commit fixes for build and
configure (please, send me an e-mail with the patch you have applied).
When committing to the gxsm4 git repository make sure to include a
meaningful commit message. Changes without a sufficient commit message
will be reverted. Commit messages should have the following format:
=== begin example commit ===
Short explanation of the commit
Longer explanation explaining exactly what's changed, whether any
external or private interfaces changed, what bugs were fixed (with bug
tracker reference if applicable) and so forth. Be concise but not too brief.
=== end example commit ===
- Always add a brief description of the commit to the _first_ line of
the commit and terminate by two newlines (it will work without the
second newline, but that is not nice for the interfaces).
- First line (the brief description) must only be one sentence and
should start with a capital letter unless it starts with a lowercase
symbol or identifier. Don't use a trailing period either. Don't exceed
72 characters.
- The main description (the body) is normal prose and should use normal
punctuation and capital letters where appropriate. Normally, for patches
sent to a mailing list it's copied from there.
- When committing code on behalf of others use the --author option, e.g.
git commit -a --author "Joe Coder <[email protected]>" and --signoff.
Code conventions
================
You may encounter old code that doesn't follow all the following code
conventions, but for new code it is better to follow them, for consistency.
- Avoid trailing whitespace.
- Indent the C code with tabulations with a width of eight characters.
use this for emacsen editors in the very first line of every source file to recognize the style:
/* -*- Mode: C++; indent-tabs-mode: nil; c-basic-offset: 8 c-style: "K&R" -*- */
- The files should have a modeline for the indentation style.
- All blocks should be surrounded by curly braces, even one-line blocks. It
spaces out the code, and it is more convenient when some code must be added
or removed without the need to add or remove the curly braces.
*** however, simple small code fragments may be excluded from this rule if easy to read.
- As a general rule of thumb, follow the same coding style as the surrounding
code.
- Do not be cheap about blank lines, spacing the code vertically help
readability. However never use two consecutive blank lines, there is really
no need.
Programming best practices
==========================
gxsm is a pretty big piece of software, or close to a large scale
project, developed well over a decade by different people and GNOME
technologies. Some parts of the code may be a little old. So when
editing the code, we should try to make it better, not worse.
It is a C++ code base in it's deep core but for the gtk3 GUI we stay
with plain C calls -- no gtkmm.
This code you are having here is the most recent port to Gtk3 and it
was a very major move and overhaul of the GUI going deep into the GUI
functionality and design due to major behind the scenes changes from
gnome-ui/gtk2 and related not outdated libraries we finally got all
rid of. We stay as of now with the very core gtk3 and glib.
Here are some general advices.
- Simplicity: the simpler code the better. Any trick that seem smart when you
write it is going to bite your ass later when reading the code. Given that
you spend 90% of the time staring at the code and 10% writing it, making
reading the code harder is a net loss.
- Brevity: make an effort to refactor common code into utility functions and
use library function whenever is possible: every time you cut and paste a
line of code you are throwing away all the precious seconds of your life
that you will later spend trying to figure out the differences among the two
copies that will have surely diverged.
- Code for change: code is bound to contain bugs no matter how well it is
written. A good coding style allows to fix these bugs with minimal changes
instead of reformatting a whole section of unrelated code, this is
especially important to make patch review easier and to easily understand
the commit history. Some practical examples are:
- Factor code into self contained functions so that changing a function
does not require to change all the callers.
- Do not align variable declaration, "case" statements etc, since this
will inevitably mean that when a line will change you'll have to
reformat all the surrounding ones.
- Declare variables in the strictest scope as possible.
- Reorder functions so that you do not need prototypes for static
functions so that when you change them you need to change them only in
one place.
- Self documentation and code comments: use code comments parsimoniously. Code
should be written so that it is clear and evident without the need of
comments. Besides, comments usually get outdated when the code is changed
and they become misleading. In particular avoid stating the obvious e.g. "a
= 1; /* assign 1 to a */". Use good function names and variables to make the
code self-documented.
A good function name is one that explain clearly all what its code really
does. There shouldn't be hidden features. If you can not find easily a good
function name, you should probably split the function in smaller pieces. A
function should do only one thing, but do it well.
Please avoid lots of one-letter variables. And a variable should be used for
only one purpose.
Self-documentation is obviously not always possible, so when a comment is
needed, it is needed. In those cases make sure to explain why and not only
how a specific thing is done: you can deduce the "how" from the code, but
not the "why". Public library functions should always be documented and in
particular should include the calling conventions, e.g. if the result should
be freed by the caller.
Do not use fancy frames around comments like a line full of
/*---------------*/ etc.
- Contribute below on the stack. Fix a problem at the right place, instead of
writing hacks to work around a bug or a lack of feature in an underlying
library.
See also
========
https://gxsm.sf.net
Thanks,
The gxsm team.