-------------------------
[updated from the C++STYLE distributed 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. This document is still incomplete.
+The aim of this file is to serve as a guide for the developers, to aid
+us to get clean and uniform code. This document is incomplete.
We really like to have new developers joining the LyX Project. However,
we have had problems in the past with developers leaving the
but still, we don't want it to happen again. So we have put together
some guidelines and rules for the developers.
+
General
-------
send patches that implements or fixes several different things; several
patches is a much better option.
-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:
-
-1999-12-13 Lars Gullik Bjønnes <larsbj@lyx.org>
+We also require you to provide a commit message entry with every patch,
+this describes in detail what the patch is doing.
- * src/support/lyxstring.C (find): assert bug fixed.
-
-Note that there are specific ChangeLogs for most directories; use those
-rather than the top-level one.
Code Constructs
---------------
user defined types, and these can very often be expensive to
initialize. This rule connects to the next rule too.
-- declare the variable as const if you don't need to change it. This
+- Declare the variable as const if you don't need to change it. This
applies to POD types like int as well as classes.
- Make the scope of a variable as small as possible.
++T;
--U;
-NOT-
- T++; // wrong
- U--; // wrong
+ T++; // not used in LyX
+ U--; // not used in LyX
- Try to minimize evaluation of the same code over and over. This is
aimed especially at loops.
compiler ensure that all cases are exhausted.
enum Foo {
- foo,
- bar
+ FOO_BAR1,
+ FOO_BAR2
};
Foo f = ...;
switch (f) {
- case foo: ...; break;
- case bar: ...; break;
+ case FOO_BAR1: ...; break;
+ case FOO_BAR2: ...; break;
default: ...; break; // not needed and would shadow a wrong use of Foo
}
+
Exceptions
----------
-Even if LyX currently is not using exceptions we need to be aware of
-them. One important thing to realize is that you often do not have to
-use throw, try or catch to be exception safe. Let's look at the
-different types of exceptions safety: (These are taken from Herb
-Sutter's book[ExC++]
+Be aware of the presence of exceptions. One important thing to realize
+is that you often do not have to use throw, try or catch to be exception
+safe. Let's look at the different types of exceptions safety: (These are
+taken from Herb Sutter's book[ExC++]
"
1. Basic guarantee: Even in the presence of exceptions thrown by T or
should look over all destructors to ensure that they are as exception
safe as possible.
-Later when more compiler support exceptions sufficiently well we will
-begin using them too. One reason for this is that the C++ standard
-library actually requires exceptions, e.g. "new" will throw
-bad_allocation if the requested memory is not available.
-
Formatting
----------
int a;
int b;
-NOT-
- int a, b; // wrong
+ int a, b; // not used in LyX
This is especially important when initialization is done at the same
time:
- string a("Lars");
- string b("Gullik");
+ string a = "Lars";
+ string b = "Gullik";
-NOT-
- string a("Lars"), b("Gullik"); // wrong
+ string a = "Lars", b = "Gullik"; // not used in LyX
+
+ [Note that 'string a = "Lars"' is formally calling a copy constructor
+ on a temporary constructed from a string literal and therefore has the
+ potential of being more expensive then direct construction by
+ 'string a("Lars")'. However the compiler is allowed to elide the copy
+ (even if it had side effects), and modern compilers typically do so.
+ Given these equal costs, LyX code favours the '=' idiom as it is in
+ line with the traditional C-style initialization, _and_ cannot be
+ mistaken as function declaration, _and_ reduces the level of nested
+ parantheses in more initializations.]
+
* Pointers and references
char * p = "flop";
char & c = *p;
-NOT-
- char *p = "flop"; // wrong
- char &c = *p; // wrong
+ char *p = "flop"; // not used in LyX
+ char &c = *p; // not used in LyX
Some time ago we had a huge discussion 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; // wrong
+ const char * p; // not used in LyX
* Operator names and parentheses
operator==(type)
-NOT-
- operator == (type) // wrong
+ operator == (type) // not used in LyX
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
+ void mangle () // not used in LyX
* Enumerators
- enum {
- one = 1,
- two = 2,
- three = 3
+ enum Foo {
+ FOO_ONE = 1,
+ FOO_TWO = 2,
+ FOO_THREE = 3
};
-NOT-
- enum { one = 1, two = 2, three 3 }; // wrong
+ enum { one = 1, two = 2, three 3 }; // not used in LyX
-NOT-
enum {
- ONE = 1,
- TWO = 2,
- THREE = 3
+ One = 1,
+ Two = 2,
+ Three = 3
};
+* Null pointers
+
+ Using a plain 0 is always correct and least effort to type. So:
+
+ void * p = 0;
+ -NOT-
+ void * p = NULL; // not used in LyX
+ -NOT-
+ void * p = '\0'; // not used in LyX
+ -NOT-
+ void * p = 42 - 7 * 6; // not used in LyX
+
+ Note: As an exception, imported third party code as well as code
+ interfacing the "native" APIs (src/support/os_*) can use NULL.
+
* 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]
+ - Use descriptive but simple and short names. Do not abbreviate.
- Class names are usually capitalized, and function names lowercased.
Enums are named like Classes, values are usually in lower-case.
- - Long variables are named like thisLongVariableName.
+ - Public API is camel-case ('void setAFlagToAValue(bool)')
+
+ - Members variables are underscored ('enable_this_feature_flag_') with a final '_'
+
+ - private/protected functions are also camel-case
+
+ - Each class is implemented in a separate pair of .h/.cpp files named like
+ the class. Exceptions are tiny helper classes which are closely tied to
+ the main class.
+
New types are capitalized, so this goes for typedefs, classes, structs
and enums.
* Use existing structures
- Use string wherever possible. LyX will someday move to Unicode, and
- that will be easy if everybody uses string now.
+ that will be easy if everybody uses string now. Unicode strings
+ should prefer using docstring instead of UTF-8 encoded std::string.
- 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.
+ - Check out the string tools in lstring.h.
- - Use the DebugStream class to report errors and messages using
+ - Use the LyXErr class to report errors and messages using
the lyxerr instantiation.
[add description of other existing structures]
- 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
- very private stuff like the math stack.
+ - Avoid global or static variables.
* File headers
like this :
/**
- * \file NewFile.C
+ * \file NewFile.cpp
* This file is part of LyX, the document processor.
* Licence details can be found in the file COPYING.
*
- The documentation is generated from the header files.
- You document for the other developers, not for yourself.
- You should document what the function does, not the implementation.
- - in the .C files you document the implementation.
+ - in the .cpp files you document the implementation.
- Single line description (///), multiple lines description (/** ... */)
- see the doxygen webpage referenced above
projects / lyx.git / blobdiff