+Note that there are specific ChangeLogs for most directories; use those
+rather than the top-level one.
+
+Code Constructs
+---------------
+
+We have several guidelines on code constructs, some of these exist to
+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
+ initialize. This rule connects to the next rule too.
+
+- 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.
+
+- Make good use of namespaces. Prefer anonymous namespaces to declaring
+ "static" for file scope.
+
+- Prefer preincrement to postincrement whenever possible.
+ Preincrement has potential of being faster than postincrement. Just
+ think about the obvious implementations of pre/post-increment. This
+ rule applies to decrement too.
+
+ ++T;
+ --U;
+ -NOT-
+ T++; // wrong
+ U--; // wrong
+
+- Try to minimize evaluation of the same code over and over. This is
+ aimed especially at loops.
+
+ Container::iterator end = large.end();
+ for (Container::iterator it = large.begin(); it != end; ++it) {
+ ...;
+ }
+ -NOT-
+ for (Container::iterator it = large.begin();
+ it != large.end(); ++it) {
+ ...;
+ }
+
+- For functions and methods that return a non-POD type T, return T
+ const instead. This gives better type checking, and will give a
+ compiler warning when temporaries are used wrongly.
+
+ T const add(...);
+ -NOT-
+ T add(...);
+
+- 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.
+
+ enum Foo {
+ foo,
+ bar
+ };
+ Foo f = ...;
+ switch (f) {
+ case foo: ...; break;
+ case bar: ...; 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++]
+
+"
+1. Basic guarantee: Even in the presence of exceptions thrown by T or
+ other exceptions, Stack objects don't leak resources.
+ Note that this also implies that the container will be
+ destructible and usable even if an exception is thrown while
+ performing some container operation. However, if an exception
+ is thrown, the container will be in a consistent, but not
+ necessarily predictable, state. Containers that support the
+ basic guarantee can work safely in some settings.
+
+2. Strong guarantee: If an operation terminates because of an
+ exception, program state will remain unchanged.
+ This always implies commit-or-rollback semantics, including
+ that no references or iterators into the container be
+ invalidated if an operation fails. For example, if a Stack
+ client calls Top and then attempts a Push that fails because
+ of an exception, then the state of the Stack object must be
+ unchanged and the reference returned from the prior call to
+ Top must still be valid. For more information on these
+ guarantees, see Dave Abrahams's documentation of the SGI
+ exception-safe standard library adaption at:
+
+ http://www.stlport.org/doc/exception_safety.html
+
+ Probably the most interesting point here is that when you
+ implement the basic guarantee, the strong guarantee often
+ comes for free. For example, in our Stack implementation,
+ almost everything we did was needed to satisfy just the basic
+ guarantee -- and what's presented above very nearly satisfies
+ the strong guarantee, with little of no extra work. Not half
+ bad, considering all the trouble we went to.
+
+ In addition to these two guarantees, there is one more
+ guarantee that certain functions must provide in order to make
+ overall exception safety possible:
+
+3. Nothrow guarantee: The function will not emit an exception under any
+ circumstances.
+ Overall exception safety isn't possible unless certain
+ 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().
+"
+
+For all cases where we might be able to write exception safe functions
+without using try, throw or catch we should do so. In particular we
+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
+----------
+
+* Only one declaration on each line.
+ int a;
+ int b;
+ -NOT-
+ int a, b; // wrong
+ This is especially important when initialization is done at the same
+ time:
+ string a("Lars");
+ string b("Gullik");
+ -NOT-
+ string a("Lars"), b("Gullik"); // wrong
+