General
-------
-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
+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.
-In general, if you want to contribute to the main source, we expect at least
+In general, if you want to contribute to the main source, we expect at least
that you:
- the most important rule first: kiss (keep it simple stupid), always
use a simple implementation in favor of a more complicated one.
This eases maintenance a lot.
-- write good C++ code: Readable, well commented and taking advantage of the
+- write good C++ code: Readable, well commented and taking advantage of the
OO model. Follow the formatting guidelines. See Formatting.
-- adapt the code to the structures already existing in LyX, or in the case that
- you have better ideas, discuss them on the developer's list before writing
- the code.
+- adapt the code to the structures already existing in LyX, or in the case
+ that you have better ideas, discuss them on the developer's list before
+ writing the code.
- take advantage of the C++ standard library. especially don't use
custom containers when a standard container is usable; learn to use
the algorithms and functors in the standard library.
---------------
It is implicitly understood that all patches contributed to The LyX
-Project is under the Gnu General Public License, version 2 or later.
+Project is under the Gnu General Public License, version 2 or later.
If you have a problem with that, don't contribute code.
Also please don't just pop up out of the blue with a huge patch (or
send patches that implements or fixes several different things; several
patches is a much better option.
-We also expect you to provide a ChangeLog entry with every patch, this
+We also require you to provide a ChangeLog entry with every patch, this
describes shortly what the patch is doing. The ChangeLog entry follows
this syntax:
make the code faster, others to make the code clearer. Yet others
exist to allow us to take advantage of the strong type checking
in C++.
-
+
- Declaration of variables should wait as long as possible. The rule
is: "Don't declare it until you need it." In C++ there are a lot of
user defined types, and these can very often be expensive to
- Prefer preincrement to postincrement whenever possible.
Preincrement has potential of being faster than postincrement. Just
- thing about the obvious implementations of pre/post-increment. This
+ think about the obvious implementations of pre/post-increment. This
rule applies to decrement too.
++T;
- Avoid using the default cases in switch statements unless you have
too. Use the correct type for the switch expression and let the
- compiler ensure that all cases are exhausted.
+ compiler ensure that all cases are exhausted.
enum Foo {
foo,
In addition to these two guarantees, there is one more
guarantee that certain functions must provide in order to make
- overall exception safety possible:
+ overall exception safety possible:
3. Nothrow guarantee: The function will not emit an exception under any
circumstances.
functions are guaranteed not to throw. In particular, we've
seen that this is true for destructors; later in this
miniseries, we'll see that it's also needed in certain helper
- functions, such as Swap().
+ functions, such as Swap().
"
For all cases where we might be able to write exception safe functions
};
-NOT-
enum { one = 1, two = 2, three 3 }; // wrong
+ -NOT-
+ enum {
+ ONE = 1,
+ TWO = 2,
+ THREE = 3
+ };
* Naming rules for classes
* 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.
- (a pity - jbl)
-
+ - Adapt the formatting of your code to the one used in the
+ other parts of LyX. In case there is different formatting for
+ the same construct, use the one used more often.
* Use 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). [Obviously 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 declaring global objects in the declaration file of the class.
+
+ - Avoid declaring global objects in the declaration file of the class.
If the same variable is used for all objects, use a static member.
- - Avoid global or static variables. An exception to this rule is
+ - Avoid global or static variables. An exception to this rule is
very private stuff like the math stack.
* File headers
- - If you create a new file, the top of the file should look something like this :
+ - If you create a new file, the top of the file should look something
+ like this :
/**
* \file NewFile.C
- * Copyright 2001 the LyX Team
- * See the file COPYING
+ * This file is part of LyX, the document processor.
+ * Licence details can be found in the file COPYING.
*
* \author Kaiser Sose
+ *
+ * Full author contact details are available in file CREDITS
*/
* Documentation
* 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
+
+ 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').
make f a non-member function;
else
make f a member function of C;
-
+
(I'll fill in more from Scott Meyers article when time allows.)
References