mirror of
https://git.lyx.org/repos/lyx.git
synced 2024-11-26 19:25:39 +00:00
def72111a5
git-svn-id: svn://svn.lyx.org/lyx/lyx-devel/trunk@584 a592a061-630c-0410-9148-cb99ea01b6c8
209 lines
7.6 KiB
Plaintext
209 lines
7.6 KiB
Plaintext
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 Bjønnes <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.
|
|
|
|
*************************************************************
|
|
|
|
How to create class interfaces.
|
|
(a.k.a How Non-Member Functions Improve Encapsulation)
|
|
======================================================
|
|
|
|
I recently read an article by Scott Meyers in C/C++ Users
|
|
Journal (Vol.18,No.2), where he makes a strong case on how non-member
|
|
functions makes classes more encapsulated, not less. Just to skipping
|
|
to the core of this provides us with the following algorithm for
|
|
deciding what kind of function to add to a class interface:
|
|
|
|
- We need to add a function f to the class C's API.
|
|
|
|
if (f needs to be virtual)
|
|
make f a member function of C;
|
|
else if (f is operator>> or operator<<) {
|
|
make f a non-member funtion;
|
|
if (f needs access to non-public members of C)
|
|
make f a friend of C;
|
|
} else if (f needs type conversions on its left-most argument) {
|
|
make f a non-member function;
|
|
if (f needs access to non-public members of C)
|
|
make f a friend of C;
|
|
} else if (f can be implemented via C's public interface)
|
|
make f a non-member function;
|
|
else
|
|
make f a member function of C;
|
|
|
|
Unfortunately, to make the best use of this kind of Class API's we
|
|
need namespaces. As soon as Jean-Marc stop using gcc 2.8 and other
|
|
compilers seem more or less up to date on namespaces we will begin to
|
|
use them. _BUT_ we should begin to use the above algoritm ASAP. We
|
|
should also go through old code and apply this algorithm to the
|
|
existing member functions. That will help maintainability in the
|
|
future.
|
|
|
|
(I'll feel in more from Scott Meyers article when time allows.)
|