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
|
Rules for the code in LyX
-------------------------
[updated from the C++STYLE distrubuted with the GNU C++ Standard]
The aim of this file is to serve as a guide for the developers, to aid us to
get clean and uniform code. Still uncomplete.
We really like to have new developers joining the LyX Project. However
since we have had problems in the past with developers leaving the
project and their contributed code in a far from perfect state. Most
of this happened before that we really became aware of these issues,
but still, we don't want it to happen again. So we have put together
some guidelines and rules for the developers.
In general, if you want to contribute to the main source, we expect at least
that you:
- write good C++ code: Readable, well commented and taking advantage of the
OO model.
- adapt the code to the structures already existing in LyX, or in case that
you have better ideas, discuss them on the developer's list before writing
the code.
- take advantage of the C++ standard library.
- we use the preincrement operator whenever possible, it has potential
of beeing faster than postincrement. (same goes for decrement)
- we try to give variables minimal scope.
These guidelines should save us a lot of work while cleaning up the code and
help us to have quality code. LyX has been haunted by problems coming from
unfinished projects by people who have left the team. Those problems will
hopefully disappear if the code is easy to hand over to somebody else.
When you send in a patch or commit to the LyX cvs repository we expect
you to add a ChangeLog entry. The entry should have this syntax:
1999-12-13 Lars Gullik Bjnnes <larsbj@lyx.org>
* src/support/lyxstring.C (find): assert bug fixed.
* Pointers and references
char * p = "flop";
char & c = *p;
-NOT-
char *p = "flop"; // wrong
char &c = *p; // wrong
Some time ago we had a huge discusion on this subject and after
convincing argumentation from Asger this is what we decided. Also note
that we will have:
char const * p;
-NOT-
const char * p;
* Operator names and parentheses
operator==(type)
-NOT-
operator == (type) // wrong
The == is part of the function name, separating it makes the
declaration look like an expression.
* Function names and parentheses
void mangle()
-NOT-
void mangle () // wrong
* Enumerators
enum {
one = 1,
two = 2,
three = 3
};
-NOT-
enum { one = 1, two = 2, three 3 };
* Naming rules for classes
- Use descriptive but simple and short names. For stuff specific to LyX
use LyX as prefix. Some modules, like mathed or spellchecker, could have
other prefixes.
[I am not so sure about the LyX prefix]
- Class names are usually capitalized, and function names lowercased.
Enums are named like Classes, enum values in CAPS.
- Long variables are named like thisLongVariableName.
New types are capitalized, so this goes for typedefs,classes,structs
and enums.
* Formatting
- Please adapt the formatting of your code to the setting in LyX in that
particular file. Lars and Asger are slowly, but surely moving the source
towards Linux kernel style formatting, aka K&R style. We suggest that you
also do this, but this is NOT something that has been decided generally.
* Use existing structures
- Use string whereever possible. LyX will someday move to Unicode, and
that will be easy if everybody uses string now.
- Check out the filename and path tools in filetools.h
- Check out the string tools in lstring.h, and the SubString class
and the regex class.
- Use the DebugStream class to report errors and messages using
the lyxerr instantation.
[add description of other existing structures]
* Declarations
- Use this order for the access sections of your class: public,
protected, private. The public section is interesting for every
user of the class. The private section is only of interest for the
implementors of the class (you). [Obvously not true since this is
for developers, and we do not want one developer only to be able to
read and understand the implementation of class internals. Lgb]
- Avoid to declare global objects in the declaration file of the class.
If the same variable is used for all object, use a static member.
- Avoid global or static variables. An exception to this rule is
very private stuff like the math stack.
- Use the const keyword like this: char const * instead of const char *
because this is more logical.
* Documentation
- The documentation is generated from the header files.
- You document for the other developers, not for yourself.
- You should document what the funtion do, not the implementation.
- in the .C files you document the implementation.
- Single line description (///), multiple lines description (/** ... */)
- You make the documentation by doing "make srcdoc" in the root,
and then you'll find HTML in the srcdoc/ directory. Read with
Netscape for best results.
* NAMING RULES FOR USER-COMMANDS
Here's the set of rules to apply when a new command name is introduced:
1) Use the object.event order. That is, use `word-forward' instead of
`forward-word'.
2) Don't introduce an alias for an already named object. Same for events.
3) Forward movement or focus is called `forward' (not `right').
4) Backward movement or focus is called `backward' (not `left').
5) Upward movement of focus is called `up'.
6) Downward movement is called `down'.
7) The begin of an object is called `begin' (not `start').
8) The end of an object is called `end'.
* Using external GUI constructors (XForms fdesign)
- Fdesign generated files should not be changed at all. The only changes
needed are gettext, compability with 0.81 or when you have made your own
xforms objects and have just a dummy in the .fd file in place of your
own. In case you have to change the generated files for any of the
reasons above, you should provide a patch against the clean generated
file. Your callbacks must be in a separate file.
|
