Update coding rule for enums to reflect actually used style.

[lyx.git] / development / coding / Rules

diff --git a/development/coding/Rules b/development/coding/Rules
index 2212a6140b025464f648328a8aa073d6c61eee05..f2a1b6e14014bfd882a3061da03563398141c37a 100644 (file)
--- a/development/coding/Rules
+++ b/development/coding/Rules
@@ -12,6 +12,7 @@ of this happened before 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.
 
+
 General
 -------
 
@@ -61,16 +62,9 @@ lot easier to read than the other diff formats. Also please do not
 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>
-
-       * src/support/lyxstring.C (find): assert bug fixed.
+We also require you to provide a commit message entry with every patch,
+this describes in detail what the patch is doing.
 
-Note that there are specific ChangeLogs for most directories; use those
-rather than the top-level one.
 
 Code Constructs
 ---------------
@@ -85,7 +79,7 @@ in C++.
   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.
@@ -130,16 +124,17 @@ in C++.
   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
 ----------
 
@@ -215,10 +210,21 @@ Formatting
        int a, b; // wrong
   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"; // wrong
+
+       [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";
@@ -248,26 +254,23 @@ Formatting
        void mangle ()  // wrong
 
 * 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
        -NOT-
        enum {
-               ONE = 1,
-               TWO = 2,
-               THREE = 3
+               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]
+  - 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.
@@ -286,14 +289,14 @@ Formatting
 * 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]
@@ -321,7 +324,7 @@ Formatting
     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.
    *
@@ -335,7 +338,7 @@ Formatting
   - 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