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
|
How to contribute to libgedit-gtksourceview
===========================================
Git commit messages
-------------------
Convention: the first line (a short description) should contain at most 72
characters.
C code conventions
------------------
See https://gitlab.gnome.org/World/gedit/gedit/-/tree/master/docs/guidelines/
In the tools/ directory there is an uncrustify config file with a script to
apply the coding style to a certain *.c file. The script has not (yet) been run
on all the libgedit-gtksourceview source code, but it can serve as a guideline.
Programming best-practices
--------------------------
libgedit-gtksourceview is a sizeable piece of software, developed over the years
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.
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. In fact, a
code is read far more often than it is written: for fixing a bug, adding a
feature, or simply see how it is implemented. So making the code harder to
read is a net loss.
- Avoid code duplication, make an effort to refactor common code into utility
functions.
- Write self-documented code when possible: instead of writing comments, it
is often possible to make the code self-documented by choosing good names
for the variables, functions and types.
Please avoid lots of one-letter variable names, it makes the code hard to
understand. Don't be afraid to write long variable names. Also, a variable
should be used for only one purpose.
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.
- About comments:
Do not write comments to state the obvious, for example avoid:
i = 0; /* assign 0 to i */
Of course, write GTK-Doc comments to document the public API, especially
the class descriptions. The class descriptions gives a nice overview when
someone discovers the library.
For a private class, it is useful to write a comment at the top describing
in a few lines what the class does.
Document well the data structures: the invariants (what is or should be
always true about certain data fields); for a list, what is the element
type; for a hash table, what are the key and value types; etc. It is more
important to document the data structures than the functions, because when
understanding well the data structures, the functions implementation should
be for the most part obvious.
When it isn't obvious, it is more important to explain *why* something is
implemented in this way, not the *how*. You can deduce the *how* from the
code, but not the *why*.
If a non-trivial feature was previously implemented in a different way,
it's useful to write a comment to describe in a few lines the previous
implementation(s), and why it has been changed (for example to fix some
problems). It permits to avoid repeating history, otherwise a new developer
might wonder why a certain feature is implemented in "this complicated way"
and not in "that simpler obvious way". For such things, a comment in the
code has more chances to be read than an old commit message (especially if
the code has been copied from one repository to another).
- Ideally, contribute below on the stack. Fix a problem at the right place,
instead of writing hacks or heuristics to work around a bug or a lack of
feature in an underlying library.
|
