Merge CodingRulesAndAdvice into Development.lyx

[Yuriy Skalko]

>> P.S. I've tried to search for some docs on Changers in LyX repository and
>> found this useful document: development/coding/CodingRulesAndAdvice.lyx.
>> Maybe it will be reasonable to merge it into lib/doc/Development.lyx so that
>> developer documentation will be in one place?
> 
> 
> +1 probably would need to update it.
> 
> Scott

Done in attached patch. Also I slightly lyxified new chapters, but 
definitely it needs an update.


Yuriy
-------------- next part --------------
From 575daeea29e90e17b2d82f14408f9866cf63d2a9 Mon Sep 17 00:00:00 2001
From: Yuriy Skalko <yuriy.skalko at gmail.com>
Date: Wed, 11 Nov 2020 13:44:39 +0200
Subject: [PATCH 2/2] Merge CodingRulesAndAdvice.lyx into Development.lyx

---
 development/coding/CodingRulesAndAdvice.lyx | 1806 ----------------
 lib/doc/Development.lyx                     | 2042 ++++++++++++++++++-
 2 files changed, 1994 insertions(+), 1854 deletions(-)
 delete mode 100644 development/coding/CodingRulesAndAdvice.lyx

diff --git a/development/coding/CodingRulesAndAdvice.lyx b/development/coding/CodingRulesAndAdvice.lyx
deleted file mode 100644
index ee1f09e61a..0000000000
--- a/development/coding/CodingRulesAndAdvice.lyx
+++ /dev/null
@@ -1,1806 +0,0 @@
-#LyX 2.0.0svn created this file. For more info see http://www.lyx.org/
-\lyxformat 345
-\begin_document
-\begin_header
-\textclass scrbook
-\use_default_options true
-\language english
-\inputencoding auto
-\font_roman default
-\font_sans default
-\font_typewriter default
-\font_default_family default
-\font_sc false
-\font_osf false
-\font_sf_scale 100
-\font_tt_scale 100
-\graphics default
-\paperfontsize default
-\spacing single
-\use_hyperref false
-\papersize default
-\use_geometry false
-\use_amsmath 1
-\use_esint 1
-\cite_engine basic
-\use_bibtopic false
-\paperorientation portrait
-\secnumdepth 3
-\tocdepth 3
-\paragraph_separation indent
-\quotes_language english
-\papercolumns 1
-\papersides 1
-\paperpagestyle default
-\listings_params "basicstyle={\footnotesize}"
-\tracking_changes true
-\output_changes false
-\author "Kornel Benko" Kornel.Benko at berlin.de
-\end_header
-
-\begin_body
-
-\begin_layout Title
-LyX Development
-\begin_inset Newline newline
-\end_inset
-
-Rules and Recommendations
-\end_layout
-
-\begin_layout Chapter
-Rules for the code in LyX
-\begin_inset Foot
-status collapsed
-
-\begin_layout Plain Layout
-Updated from the C++STYLE distributed with the GNU C++ Standard.
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout 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 incomplete.
- We really like to have new developers joining the LyX Project.
- However, 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 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.
-\end_layout
-
-\begin_layout Section
-General
-\end_layout
-
-\begin_layout Standard
-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 that you:
-\end_layout
-
-\begin_layout Itemize
-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.
-\end_layout
-
-\begin_layout Itemize
-write good C++ code: Readable, well commented and taking advantage of the
- OO model.
- Follow the formatting guidelines.
- See Formatting.
-\end_layout
-
-\begin_layout Itemize
-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.
-\end_layout
-
-\begin_layout Itemize
-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.
-\end_layout
-
-\begin_layout Itemize
-be aware of exceptions and write exception safe code.
- See Exceptions.
-\end_layout
-
-\begin_layout Itemize
-document all variables, methods, functions, classes etc.
- We are using the source documentation program doxygen, a program that handles
- javadoc syntax, to document sources.
- You can download doxygen from: http://www.stack.nl/~dimitri/doxygen/
-\end_layout
-
-\begin_layout Itemize
-we have certain code constructs that we try to follow.
- See Code Constructs.
-\end_layout
-
-\begin_layout Section
-Submitting Code
-\end_layout
-
-\begin_layout Standard
-It is implicitly understood that all patches contributed to The LyX 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 small)
- that changes something substantial in LyX.
- Always discuss your ideas with the developers on the developer's mailing
- list.
- When you create the patch, please use "diff -up" since we find that a 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 commit message entry with every patch,
- this describes in detail what the patch is doing.
- 
-\end_layout
-
-\begin_layout Section
-Code Constructs
-\end_layout
-
-\begin_layout Standard
-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++.
- 
-\end_layout
-
-\begin_layout Itemize
-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.
- 
-\end_layout
-
-\begin_layout Itemize
-Declare the variable as const if you don't need to change it.
- This applies to POD types like int as well as classes.
- 
-\end_layout
-
-\begin_layout Itemize
-Make the scope of a variable as small as possible.
-\end_layout
-
-\begin_layout Itemize
-Make good use of namespaces.
- Prefer anonymous namespaces to declaring "static" for file scope.
-\end_layout
-
-\begin_layout Itemize
-Prefer preincrement to postincrement whenever possible.
-\end_layout
-
-\begin_layout Itemize
-Preincrement has potential of being faster than postincrement.
- Just think about the obvious implementations of pre/post-increment.
- This rule applies to decrement too.
-\end_layout
-
-\begin_layout Itemize
-Use:
-\end_layout
-
-\begin_deeper
-\begin_layout Standard
-\begin_inset listings
-lstparams "basicstyle={\footnotesize},language={C++}"
-inline false
-status open
-
-\begin_layout Plain Layout
-
-++T;
-\end_layout
-
-\begin_layout Plain Layout
-
---U;
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-Do not use:
-\end_layout
-
-\begin_layout Standard
-\begin_inset listings
-inline false
-status open
-
-\begin_layout Plain Layout
-
-T++; // not used in LyX
-\end_layout
-
-\begin_layout Plain Layout
-
-U--;// not used in LyX
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_deeper
-\begin_layout Itemize
-Try to minimize evaluation of the same code over and over.
- This is aimed especially at loops.
- 
-\begin_inset Newline newline
-\end_inset
-
-Use:
-\end_layout
-
-\begin_deeper
-\begin_layout Standard
-\begin_inset listings
-inline false
-status open
-
-\begin_layout Plain Layout
-
-Container::iterator end = large.end();
-\end_layout
-
-\begin_layout Plain Layout
-
-for (Container::iterator it = large.begin(); it != end; ++it) {
-\end_layout
-
-\begin_layout Plain Layout
-
-	...;
-\end_layout
-
-\begin_layout Plain Layout
-
-}
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-Do not use:
-\end_layout
-
-\begin_layout Standard
-\begin_inset listings
-inline false
-status open
-
-\begin_layout Plain Layout
-
-for (Container::iterator it = large.begin(); it != large.end(); ++it) {
-\end_layout
-
-\begin_layout Plain Layout
-
-	...;
-\end_layout
-
-\begin_layout Plain Layout
-
-}
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_deeper
-\begin_layout Itemize
-For functions and methods that return a non-POD type
-\begin_inset Foot
-status open
-
-\begin_layout Plain Layout
-Plain Ol' Data type
-\end_layout
-
-\end_inset
-
- T, return T const instead.
- This gives better type checking, and will give a compiler warning when
- temporaries are used wrongly.
-\end_layout
-
-\begin_deeper
-\begin_layout Standard
-Use:
-\end_layout
-
-\begin_layout Standard
-\begin_inset listings
-inline false
-status open
-
-\begin_layout Plain Layout
-
-T const add(..);
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-Do not use:
-\end_layout
-
-\begin_layout Standard
-\begin_inset listings
-inline false
-status open
-
-\begin_layout Plain Layout
-
-T add(..);
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_deeper
-\begin_layout Itemize
-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.
-\end_layout
-
-\begin_layout Itemize
-\begin_inset listings
-inline false
-status open
-
-\begin_layout Plain Layout
-
-enum Foo {
-\end_layout
-
-\begin_layout Plain Layout
-
-	FOO_BAR1,
-\end_layout
-
-\begin_layout Plain Layout
-
-	FOO_BAR2
-\end_layout
-
-\begin_layout Plain Layout
-
-};
-\end_layout
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\begin_layout Plain Layout
-
-Foo f = ...;
-\end_layout
-
-\begin_layout Plain Layout
-
-\end_layout
-
-\begin_layout Plain Layout
-
-switch (f) {
-\end_layout
-
-\begin_layout Plain Layout
-
-	case FOO_BAR1: ...; 
-\end_layout
-
-\begin_layout Plain Layout
-
-		break;
-\end_layout
-
-\begin_layout Plain Layout
-
-	case FOO_BAR2: ...; 
-\end_layout
-
-\begin_layout Plain Layout
-
-		break;
-\end_layout
-
-\begin_layout Plain Layout
-
-	default: ...; 
-\end_layout
-
-\begin_layout Plain Layout
-
-		// not needed and would shadow a wrong use of Foo
-\end_layout
-
-\begin_layout Plain Layout
-
-		break; 
-\end_layout
-
-\begin_layout Plain Layout
-
-}
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Section
-Exceptions
-\end_layout
-
-\begin_layout Standard
-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++] 
-\end_layout
-
-\begin_layout Enumerate
-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.
- 
-\end_layout
-
-\begin_layout Enumerate
-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/do
-c/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 o
-\change_inserted 0 1288157484
-r
-\change_deleted 0 1288157483
-f
-\change_unchanged
- 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:
-\end_layout
-
-\begin_layout Enumerate
-No throw guarantee: The function will not emit an exception under any circumstan
-ces.
- 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().
-\end_layout
-
-\begin_layout Standard
-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.
-\end_layout
-
-\begin_layout Section
-Formatting
-\end_layout
-
-\begin_layout Itemize
-Only one declaration on each line.
-\end_layout
-
-\begin_deeper
-\begin_layout Standard
-Use:
-\end_layout
-
-\begin_layout Standard
-\begin_inset listings
-inline false
-status open
-
-\begin_layout Plain Layout
-
-int a;
-\end_layout
-
-\begin_layout Plain Layout
-
-int b;
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-Do not use:
-\end_layout
-
-\begin_layout Standard
-\begin_inset listings
-inline false
-status open
-
-\begin_layout Plain Layout
-
-int a,b; // not used in LyX
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-This is especially important when initialization is done at the same time:
-\end_layout
-
-\begin_layout Standard
-Use:
-\end_layout
-
-\begin_layout Standard
-\begin_inset listings
-inline false
-status open
-
-\begin_layout Plain Layout
-
-string a = "Lars";
-\end_layout
-
-\begin_layout Plain Layout
-
-string b = "Gullik";
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-Do not use:
-\end_layout
-
-\begin_layout Standard
-\begin_inset listings
-inline false
-status open
-
-\begin_layout Plain Layout
-
-string a = "Lars", b = "Gullik"; // not used in LyX
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-[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.]
-\end_layout
-
-\end_deeper
-\begin_layout Itemize
-Pointers and references:
-\end_layout
-
-\begin_deeper
-\begin_layout Standard
-Use:
-\end_layout
-
-\begin_layout Standard
-\begin_inset listings
-inline false
-status open
-
-\begin_layout Plain Layout
-
-char * p = "flop";
-\end_layout
-
-\begin_layout Plain Layout
-
-char & c = *p;
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-Do not use:
-\end_layout
-
-\begin_layout Standard
-\begin_inset listings
-inline false
-status open
-
-\begin_layout Plain Layout
-
-char *p = "flop"; // not used in LyX
-\end_layout
-
-\begin_layout Plain Layout
-
-char &c = *p; // not used in LyX
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-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:
-\end_layout
-
-\begin_layout Standard
-\begin_inset listings
-inline false
-status open
-
-\begin_layout Plain Layout
-
-char const * p;
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-and not
-\end_layout
-
-\begin_layout Standard
-\begin_inset listings
-inline false
-status open
-
-\begin_layout Plain Layout
-
-const char * p; // not used in LyX
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_deeper
-\begin_layout Itemize
-Operator names and parentheses
-\end_layout
-
-\begin_deeper
-\begin_layout Standard
-\begin_inset listings
-inline false
-status open
-
-\begin_layout Plain Layout
-
-operator==(type)
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-and not
-\end_layout
-
-\begin_layout Standard
-\begin_inset listings
-inline false
-status open
-
-\begin_layout Plain Layout
-
-operator == (type) // not used in LyX
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-The == is part of the function name, separating it makes the declaration
- look like an expression.
-\end_layout
-
-\end_deeper
-\begin_layout Itemize
-Function names and parentheses
-\end_layout
-
-\begin_deeper
-\begin_layout Standard
-\begin_inset listings
-inline false
-status open
-
-\begin_layout Plain Layout
-
-void mangle()
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-and not
-\end_layout
-
-\begin_layout Standard
-\begin_inset listings
-inline false
-status open
-
-\begin_layout Plain Layout
-
-void mangle () // not used in LyX
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_deeper
-\begin_layout Itemize
-Enumerators
-\end_layout
-
-\begin_deeper
-\begin_layout Standard
-\begin_inset listings
-inline false
-status open
-
-\begin_layout Plain Layout
-
-enum Foo {
-\end_layout
-
-\begin_layout Plain Layout
-
-	FOO_ONE = 1,
-\end_layout
-
-\begin_layout Plain Layout
-
-	FOO_TWO = 2,
-\end_layout
-
-\begin_layout Plain Layout
-
-	FOO_THREE = 3
-\end_layout
-
-\begin_layout Plain Layout
-
-};
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-and not
-\end_layout
-
-\begin_layout Standard
-\begin_inset listings
-inline false
-status open
-
-\begin_layout Plain Layout
-
-enum { one = 1, two = 2, three 3 }; // not used in LyX
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-and not
-\end_layout
-
-\begin_layout Standard
-\begin_inset listings
-inline false
-status open
-
-\begin_layout Plain Layout
-
-enum {
-\end_layout
-
-\begin_layout Plain Layout
-
-One = 1,
-\end_layout
-
-\begin_layout Plain Layout
-
-Two = 2,
-\end_layout
-
-\begin_layout Plain Layout
-
-Three = 3
-\end_layout
-
-\begin_layout Plain Layout
-
-};
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_deeper
-\begin_layout Itemize
-Null pointers
-\end_layout
-
-\begin_deeper
-\begin_layout Standard
-Using a plain 0 is always correct and least effort to type.
- So: 
-\end_layout
-
-\begin_layout Standard
-\begin_inset listings
-inline false
-status open
-
-\begin_layout Plain Layout
-
-void * p = 0;
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-and not
-\end_layout
-
-\begin_layout Standard
-\begin_inset listings
-inline false
-status open
-
-\begin_layout Plain Layout
-
-void * p = NULL; // not used in LyX
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-and not
-\end_layout
-
-\begin_layout Standard
-\begin_inset listings
-inline false
-status open
-
-\begin_layout Plain Layout
-
-void * p = '
-\backslash
-0'; // not used in LyX
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-and not
-\end_layout
-
-\begin_layout Standard
-\begin_inset listings
-inline false
-status open
-
-\begin_layout Plain Layout
-
-void * p = 42 - 7 * 6; // not used in LyX
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-Note: As an exception, imported third party code as well as code interfacing
- the "native" APIs (src/support/os_*) can use NULL.
-\end_layout
-
-\end_deeper
-\begin_layout Itemize
-Naming rules for classes
-\end_layout
-
-\begin_deeper
-\begin_layout Itemize
-Use descriptive but simple and short names.
- Do not abbreviate.
-\end_layout
-
-\begin_layout Itemize
-Class names are usually capitalized, and function names lowercased.
-\end_layout
-
-\begin_layout Itemize
-Enums are named like Classes, values are usually in lower-case.
-\end_layout
-
-\begin_layout Itemize
-Public API is camel-case ('void setAFlagToAValue(bool)')
-\end_layout
-
-\begin_layout Itemize
-Members variables are underscored ('enable_this_feature_flag_') with a final
- '_'
-\end_layout
-
-\begin_layout Itemize
-Private/protected functions are also camel-case
-\end_layout
-
-\begin_layout Itemize
-New types are capitalized, so this goes for typedefs, classes, structs and
- enums.
-\end_layout
-
-\end_deeper
-\begin_layout Itemize
-Formatting
-\end_layout
-
-\begin_deeper
-\begin_layout Itemize
-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.
-\end_layout
-
-\end_deeper
-\begin_layout Itemize
-Use existing structures
-\end_layout
-
-\begin_deeper
-\begin_layout Itemize
-
-\change_inserted 0 1288159254
-\begin_inset CommandInset label
-LatexCommand label
-name "Use-string-wherever"
-
-\end_inset
-
-
-\change_unchanged
-Use string wherever possible.
- LyX will someday move to Unicode, and that will be easy if everybody uses
- string now.
- Unicode strings should prefer using docstring instead of UTF-8 encoded
- std::string.
-\end_layout
-
-\begin_layout Itemize
-Check out the filename and path tools in filetools.h
-\end_layout
-
-\begin_layout Itemize
-Check out the string tools in lstring.h.
-\end_layout
-
-\begin_layout Itemize
-Use the LyXErr class to report errors and messages using the lyxerr instantiatio
-n.
- [add description of other existing structures]
-\end_layout
-
-\end_deeper
-\begin_layout Itemize
-Declarations
-\end_layout
-
-\begin_deeper
-\begin_layout Itemize
-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]
-\end_layout
-
-\begin_layout Itemize
-Avoid declaring global objects in the declaration file of the class.
- If the same variable is used for all objects, use a static member.
-\end_layout
-
-\begin_layout Itemize
-Avoid global or static variables.
-\end_layout
-
-\end_deeper
-\begin_layout Itemize
-File headers
-\end_layout
-
-\begin_deeper
-\begin_layout Standard
-If you create a new file, the top of the file should look something like
- this :
-\end_layout
-
-\begin_layout Standard
-\begin_inset listings
-inline false
-status open
-
-\begin_layout Plain Layout
-
-/**
-\end_layout
-
-\begin_layout Plain Layout
-
-* 
-\backslash
-file NewFile.cpp
-\end_layout
-
-\begin_layout Plain Layout
-
-* This file is part of LyX, the document processor.
-\end_layout
-
-\begin_layout Plain Layout
-
-* Licence details can be found in the file COPYING.
-\end_layout
-
-\begin_layout Plain Layout
-
-*
-\end_layout
-
-\begin_layout Plain Layout
-
-* 
-\backslash
-author Kaiser Sose
-\end_layout
-
-\begin_layout Plain Layout
-
-*
-\end_layout
-
-\begin_layout Plain Layout
-
-* Full author contact details are available in file CREDITS
-\end_layout
-
-\begin_layout Plain Layout
-
-*/
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_deeper
-\begin_layout Itemize
-Documentation
-\end_layout
-
-\begin_deeper
-\begin_layout Itemize
-The documentation is generated from the header files.
-\end_layout
-
-\begin_layout Itemize
-You document for the other developers, not for yourself.
-\end_layout
-
-\begin_layout Itemize
-You should document what the function does, not the implementation.
-\end_layout
-
-\begin_deeper
-\begin_layout Itemize
-in the .cpp files you document the implementation.
-\end_layout
-
-\end_deeper
-\begin_layout Itemize
-Single line description (///), multiple lines description (/** ...
- */) see the doxygen webpage referenced above
-\end_layout
-
-\end_deeper
-\begin_layout Section
-Naming rules for Lyx User Functions (LFUNs)
-\end_layout
-
-\begin_layout Standard
-Here is the set of rules to apply when a new command name is introduced:
-\end_layout
-
-\begin_layout Enumerate
-Use the object.event order.
- That is, use `word-forward' instead of`forward-word'.
-\end_layout
-
-\begin_layout Enumerate
-Don't introduce an alias for an already named object.
- Same for events.
-\end_layout
-
-\begin_layout Enumerate
-Forward movement or focus is called `forward' (not `right').
-\end_layout
-
-\begin_layout Enumerate
-Backward movement or focus is called `backward' (not `left').
-\end_layout
-
-\begin_layout Enumerate
-Upward movement of focus is called `up'.
-\end_layout
-
-\begin_layout Enumerate
-Downward movement is called `down'.
-\end_layout
-
-\begin_layout Enumerate
-The begin of an object is called `begin' (not `start').
-\end_layout
-
-\begin_layout Enumerate
-The end of an object is called `end'.
-\end_layout
-
-\begin_layout Section
-How to create class interfaces
-\end_layout
-
-\begin_layout Standard
-(a.k.a How Non-Member Functions Improve Encapsulation)
-\end_layout
-
-\begin_layout Standard
-I recently read an article by Scott Meyers
-\change_deleted 0 1288158556
- in 
-\change_unchanged
-, where he makes a strong case on how non-member functions makes classes
- more encapsulated, not less.
- Just skipping to the core of this provides us with the following algorithm
- for deciding what kind of function to add to a class interface:
-\end_layout
-
-\begin_layout Itemize
-We need to add a function f to the class C's API.
-\end_layout
-
-\begin_deeper
-\begin_layout Standard
-\begin_inset listings
-inline false
-status open
-
-\begin_layout Plain Layout
-
-if (f needs to be virtual)
-\end_layout
-
-\begin_layout Plain Layout
-
-	make f a member function of C;
-\end_layout
-
-\begin_layout Plain Layout
-
-else if (f is operator>> or operator<<) {
-\end_layout
-
-\begin_layout Plain Layout
-
-	make f a non-member function;
-\end_layout
-
-\begin_layout Plain Layout
-
-	if (f needs access to non-public members of C)
-\end_layout
-
-\begin_layout Plain Layout
-
-		make f a friend of C;
-\end_layout
-
-\begin_layout Plain Layout
-
-} else if (f needs type conversions on its left-most argument) {
-\end_layout
-
-\begin_layout Plain Layout
-
-	make f a non-member function;
-\end_layout
-
-\begin_layout Plain Layout
-
-	if (f needs access to non-public members of C)
-\end_layout
-
-\begin_layout Plain Layout
-
-		make f a friend of C;
-\end_layout
-
-\begin_layout Plain Layout
-
-} else if (f can be implemented via C's public interface)
-\end_layout
-
-\begin_layout Plain Layout
-
-	make f a non-member function;
-\end_layout
-
-\begin_layout Plain Layout
-
-else
-\end_layout
-
-\begin_layout Plain Layout
-
-	make f a member function of C;
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\end_deeper
-\begin_layout Chapter
-Recommendations
-\end_layout
-
-\begin_layout Standard
-These are some rules for effective C++ programming.
- These are taken from Scott Meyers
-\begin_inset CommandInset citation
-LatexCommand cite
-key "key-4"
-
-\end_inset
-
-, and are presented in their short form.
- These are not all the rules Meyers presents, only the most important of
- them.
- LyX does not yet follow these rules, but they should be the goal.
-\end_layout
-
-\begin_layout Itemize
-use const and inline instead of #define
-\end_layout
-
-\begin_layout Itemize
-use the same form in corresponding calls to new and delete, i.e.
- write delete[] obj; if new obj[n]; was used to create the object and write
- delete obj; if you wrote new obj; Notice strings should be std::string's
- instead of char *'s.
-
-\change_inserted 0 1288159280
- (this contradicts to 
-\begin_inset CommandInset ref
-LatexCommand ref
-reference "Use-string-wherever"
-
-\end_inset
-
- )
-\change_unchanged
-
-\end_layout
-
-\begin_layout Itemize
-define a default constructor, copy constructor and an assignment operator
- for all classes with dynamically allocated memory that are not made noncopyable
-\end_layout
-
-\begin_layout Itemize
-do not define default constructor, copy constructor and an assignment operator
- if the compiler generated one would do the same
-\end_layout
-
-\begin_layout Itemize
-make destructors virtual in base classes and only there 
-\end_layout
-
-\begin_layout Itemize
-assign to all data members in operator=()
-\end_layout
-
-\begin_layout Itemize
-strive for class interfaces that are complete and minimal
-\end_layout
-
-\begin_layout Itemize
-differentiate among member functions, global functions and friend functions
-\end_layout
-
-\begin_layout Itemize
-avoid data members in the public interface
-\end_layout
-
-\begin_layout Itemize
-use const whenever possible
-\end_layout
-
-\begin_layout Itemize
-pass and return objects by reference instead of by value
-\end_layout
-
-\begin_layout Itemize
-choose carefully between function overloading and parameter defaulting
-\end_layout
-
-\begin_layout Itemize
-never return a reference to a local object or a dereferenced pointer initialized
- by new within the function
-\end_layout
-
-\begin_layout Itemize
-use enums for integral constants
-\end_layout
-
-\begin_layout Itemize
-minimize compilation dependencies between files
-\end_layout
-
-\begin_layout Itemize
-pay attention to compiler warnings
-\end_layout
-
-\begin_layout Itemize
-differentiate between inheritance of interface and inheritance of implementation
-\end_layout
-
-\begin_layout Itemize
-differentiate between inheritance and templates
-\end_layout
-
-\begin_layout Itemize
-ensure that global objects are initialized before they are used
-\end_layout
-
-\begin_layout Itemize
-avoid conditions to 'if' and 'while' that span more than a line
-\end_layout
-
-\begin_layout Chapter
-\start_of_appendix
-Notes
-\end_layout
-
-\begin_layout Itemize
-And one of mine: (Lgb)
-\end_layout
-
-\begin_deeper
-\begin_layout Itemize
-when swi
-\change_inserted 0 1288159389
-t
-\change_unchanged
-ching on enums, refrain from using "default:" if possible
-\end_layout
-
-\end_deeper
-\begin_layout Itemize
-And one of mine: (Andre')
-\end_layout
-
-\begin_deeper
-\begin_layout Itemize
-try to implement your class in a way that the automatically generated copy
- constructor and copy assignment work out-of-the box
-\end_layout
-
-\begin_layout Itemize
-I don't have problems with using boost in the implementation _if and only
- if_ it provides actual benefits over less intrusive alternatives.
- I do have a problem with needlessly sprinkling 'boost::' over interfaces,
- especially if it does not add any value.
-\end_layout
-
-\begin_deeper
-\begin_layout Standard
-Given that there seems to be an unconditional "typedef unsigned int quint32;"
- in qglobal.h I don't think there's any platform supported by current LyX
- that could not use 'unsigned int' (and an static assert in some implementation
- file for the unlikely case some ILP64 zombie raises its ugly head again.
- And if that happens, using <cstdint> would still be a better choice...)
-\end_layout
-
-\begin_layout Standard
-The idea is to create something that's not compilable as soon as the condition
- is violated.
- There are lots of possibilities to achieve this, some examples follow:
-\end_layout
-
-\begin_layout Standard
-In C++0x there's a "built-in":
-\end_layout
-
-\begin_layout Standard
-\begin_inset listings
-inline false
-status open
-
-\begin_layout Plain Layout
-
-static_assert(sizeof(int) == 4, "Funny platform")
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-until then on namespace scope: 
-\end_layout
-
-\begin_layout Standard
-\begin_inset listings
-inline false
-status open
-
-\begin_layout Plain Layout
-
-#include <boost/static_assert.hpp> BOOST_STATIC_ASSERT(sizeof(int) == 4)
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-or without boost:
-\end_layout
-
-\begin_layout Standard
-\begin_inset listings
-inline false
-status open
-
-\begin_layout Plain Layout
-
-template<bool Condition> struct static_assert_helper;
-\end_layout
-
-\begin_layout Plain Layout
-
-template <> struct static_assert_helper<true> {}; 
-\end_layout
-
-\begin_layout Plain Layout
-
-enum { dummy = sizeof(static_assert_helper<sizeof(int) == 4>)};
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-or somewhat brutish without templates, in any function:
-\end_layout
-
-\begin_layout Standard
-\begin_inset listings
-inline false
-status open
-
-\begin_layout Plain Layout
-
-const int d = sizeof(int) - 4;
-\end_layout
-
-\begin_layout Plain Layout
-
-switch(0) { 
-\end_layout
-
-\begin_layout Plain Layout
-
-case 0: 
-\end_layout
-
-\begin_layout Plain Layout
-
-case !(d*d): 
-\end_layout
-
-\begin_layout Plain Layout
-
-break; 
-\end_layout
-
-\begin_layout Plain Layout
-
-}
-\end_layout
-
-\end_inset
-
-
-\end_layout
-
-\begin_layout Standard
-Any of them in a .cpp file will break compilation as soon as sizeof(int)
- is not equal 4.
- Personally I prefer something like the third version (or the first, if
- using C++0x is allowed).
-\end_layout
-
-\end_deeper
-\end_deeper
-\begin_layout Itemize
-And one of mine: (vfr)
-\end_layout
-
-\begin_deeper
-\begin_layout Itemize
-On dynamics_casts 
-\begin_inset Flex URL
-status open
-
-\begin_layout Plain Layout
-
-http://www.lyx.org/trac/changeset/35855
-\end_layout
-
-\end_inset
-
-:
-\end_layout
-
-\begin_deeper
-\begin_layout Standard
-A dynamic_cast is necessary when:
-\end_layout
-
-\begin_layout Itemize
-the object to be casted is from an external library because we can't add
- Qxxx::asXxxx() to Qt e.g.:
-\end_layout
-
-\begin_deeper
-\begin_layout Itemize
-QAbstractListModel to GuiIdListModel,
-\end_layout
-
-\begin_layout Itemize
-QValidator to PathValidator,
-\end_layout
-
-\begin_layout Itemize
-QWidget to TabWorkArea,
-\end_layout
-
-\begin_layout Itemize
-QWidget to GuiWorkArea;
-\end_layout
-
-\end_deeper
-\begin_layout Itemize
-the object is to be casted from an interface to the implementing class,
- because the Interface does not know by whom it is implemented:
-\end_layout
-
-\begin_deeper
-\begin_layout Itemize
-ProgressInterface to GuiProgress,
-\end_layout
-
-\begin_layout Itemize
-Application to GuiApplication.
-\end_layout
-
-\end_deeper
-\begin_layout Standard
-A dynamic_cast can be replaced by:
-\end_layout
-
-\begin_layout Itemize
-already existing as***Inset() functions, e.g.:
-\end_layout
-
-\begin_deeper
-\begin_layout Itemize
-asHullInset(),
-\end_layout
-
-\begin_layout Itemize
-asInsetMath()->asMacro(),
-\end_layout
-
-\begin_layout Itemize
-asInsetText();
-\end_layout
-
-\end_deeper
-\begin_layout Itemize
-A static_cast when we are sure this can't go wrong, e.g.:
-\end_layout
-
-\begin_deeper
-\begin_layout Itemize
-we are sure that CellData::inset->clone() is an InsetTableCell,
-\end_layout
-
-\begin_layout Itemize
-in cases where we explicitly check it->lyxCode().
-\end_layout
-
-\end_deeper
-\end_deeper
-\end_deeper
-\begin_layout Bibliography
-\begin_inset CommandInset bibitem
-LatexCommand bibitem
-key "key-1"
-
-\end_inset
-
-S.
- Meyers.
- Effective C++, 50 Specific Ways to Improve Your Programs and Design.
- Addison-Wesley, 1992
-\end_layout
-
-\begin_layout Bibliography
-\begin_inset CommandInset bibitem
-LatexCommand bibitem
-key "key-2"
-
-\end_inset
-
-Sutter, Herb.
- Exceptional C++: 47 engineering puzzles, programming problems, and solutions.
- ISBN 0-201-61562-2
-\end_layout
-
-\begin_layout Bibliography
-\begin_inset CommandInset bibitem
-LatexCommand bibitem
-key "key-4"
-
-\end_inset
-
-Scott Meyers, C/C++ User's Journal (Vol.18,No.2)
-\end_layout
-
-\end_body
-\end_document
diff --git a/lib/doc/Development.lyx b/lib/doc/Development.lyx
index 7dfa96934b..f68b0b086d 100644
--- a/lib/doc/Development.lyx
+++ b/lib/doc/Development.lyx
@@ -1,16 +1,16 @@
 #LyX 2.4 created this file. For more info see https://www.lyx.org/
-\lyxformat 572
+\lyxformat 599
 \begin_document
 \begin_header
 \save_transient_properties true
 \origin /systemlyxdir/doc/
-\textclass scrartcl
+\textclass scrbook
 \options BCOR8mm,captions=tableheading
 \use_default_options false
 \begin_modules
 logicalmkup
 \end_modules
-\maintain_unincluded_children false
+\maintain_unincluded_children no
 \language english
 \language_package default
 \inputencoding utf8
@@ -22,7 +22,9 @@ logicalmkup
 \font_default_family default
 \use_non_tex_fonts false
 \font_sc false
-\font_osf false
+\font_roman_osf false
+\font_sans_osf false
+\font_typewriter_osf false
 \font_sf_scale 100 100
 \font_tt_scale 100 100
 \use_microtype false
@@ -32,6 +34,8 @@ logicalmkup
 \output_sync 1
 \bibtex_command default
 \index_command default
+\float_placement class
+\float_alignment class
 \paperfontsize 12
 \spacing single
 \use_hyperref true
@@ -49,7 +53,7 @@ logicalmkup
 \pdf_backref false
 \pdf_pdfusetitle false
 \pdf_quoted_options "linkcolor=black, citecolor=black, urlcolor=blue, filecolor=blue, pdfpagelayout=OneColumn, pdfnewwindow=true, pdfstartview=XYZ, plainpages=false"
-\papersize a4paper
+\papersize a4
 \use_geometry false
 \use_package amsmath 1
 \use_package amssymb 1
@@ -71,13 +75,14 @@ logicalmkup
 \justification true
 \use_refstyle 0
 \use_minted 0
+\use_lineno 0
 \notefontcolor #0000ff
 \index Index
 \shortcut idx
 \color #008000
 \end_index
 \secnumdepth 4
-\tocdepth 4
+\tocdepth 2
 \paragraph_separation indent
 \paragraph_indentation default
 \is_math_indent 0
@@ -90,9 +95,12 @@ logicalmkup
 \tablestyle default
 \tracking_changes false
 \output_changes false
+\change_bars false
+\postpone_fragile_content false
 \html_math_output 0
 \html_css_as_file 0
 \html_be_strict true
+\docbook_table_output 0
 \end_header
 
 \begin_body
@@ -103,7 +111,7 @@ Developing \SpecialChar LyX
 \end_layout
 
 \begin_layout Subtitle
-Version 2.3.x
+Version 2.4.x
 \end_layout
 
 \begin_layout Author
@@ -143,7 +151,7 @@ LatexCommand tableofcontents
 
 \end_layout
 
-\begin_layout Section
+\begin_layout Chapter
 Introduction
 \end_layout
 
@@ -176,7 +184,7 @@ development
  here.
 \end_layout
 
-\begin_layout Section
+\begin_layout Chapter
 File formats
 \end_layout
 
@@ -188,11 +196,11 @@ File formats
 tion.
 \end_layout
 
-\begin_layout Subsection
+\begin_layout Section
 File Format Numbers
 \end_layout
 
-\begin_layout Subsection
+\begin_layout Section
 When is an update of the .lyx file format number needed?
 \begin_inset CommandInset label
 LatexCommand label
@@ -406,7 +414,7 @@ reference "subsec:New-layouts"
 If you are still unsure, please ask on the development list.
 \end_layout
 
-\begin_layout Subsection
+\begin_layout Section
 \begin_inset CommandInset label
 LatexCommand label
 name "subsec:update_lyx_files"
@@ -730,7 +738,7 @@ git commit -a
 .
 \end_layout
 
-\begin_layout Subsection
+\begin_layout Section
 Updating the file format number of layout files
 \end_layout
 
@@ -805,7 +813,7 @@ status collapsed
  file format.
 \end_layout
 
-\begin_layout Subsection
+\begin_layout Section
 Updating the file format number of bind/ui files
 \end_layout
 
@@ -1032,7 +1040,7 @@ lib/lyx2lyx/lyx2lyx_tools.py
  
 \end_layout
 
-\begin_layout Subsection
+\begin_layout Section
 Backporting new styles to the stable version
 \begin_inset CommandInset label
 LatexCommand label
@@ -1129,11 +1137,11 @@ lyx2lyx
  version.
 \end_layout
 
-\begin_layout Section
+\begin_layout Chapter
 New layouts and modules
 \end_layout
 
-\begin_layout Subsection
+\begin_layout Section
 \begin_inset CommandInset label
 LatexCommand label
 name "subsec:New-layouts"
@@ -1396,7 +1404,7 @@ reference "par:when-to-run-an-export-test"
 ).
 \end_layout
 
-\begin_layout Subsection
+\begin_layout Section
 New modules
 \end_layout
 
@@ -1436,7 +1444,7 @@ Modules do not need a template, only an example, which is strongly encouraged
  but not necessarily required.
 \end_layout
 
-\begin_layout Subsection
+\begin_layout Section
 Layouts for document classes with incompatible versions
 \end_layout
 
@@ -1737,7 +1745,7 @@ This way, new documents based on the template or example will use the up-to-date
 
 \end_layout
 
-\begin_layout Section
+\begin_layout Chapter
 Tests
 \end_layout
 
@@ -1751,7 +1759,7 @@ Automated tests are an important tool to detect bugs and regressions in
  easily, and some tests of this kind exist.
 \end_layout
 
-\begin_layout Subsection
+\begin_layout Section
 unit tests
 \end_layout
 
@@ -1763,7 +1771,7 @@ There are attempts to set up a suite of unit tests for LyX.
 TODO: describe what is done and what is still to do.
 \end_layout
 
-\begin_layout Subsection
+\begin_layout Section
 tex2lyx tests
 \end_layout
 
@@ -1832,7 +1840,7 @@ status collapsed
  This may be useful for roundtrip comparisons.
 \end_layout
 
-\begin_layout Subsubsection
+\begin_layout Subsection
 Running the tests
 \end_layout
 
@@ -1930,7 +1938,7 @@ cmplyx
  are output in unified diff format.
 \end_layout
 
-\begin_layout Subsubsection
+\begin_layout Subsection
 Updating test references
 \begin_inset CommandInset label
 LatexCommand label
@@ -2095,7 +2103,7 @@ do not
  regarding insignificant whitespace and line breaks.
 \end_layout
 
-\begin_layout Subsubsection
+\begin_layout Subsection
 Adding a new test
 \end_layout
 
@@ -2170,7 +2178,7 @@ Commit the changes to the repository, or send a patch to the development
  list and ask for committing if you do not have commit rights.
 \end_layout
 
-\begin_layout Subsection
+\begin_layout Section
 ctest automatic tests
 \end_layout
 
@@ -2267,7 +2275,7 @@ build directory.
  
 \end_layout
 
-\begin_layout Subsubsection
+\begin_layout Subsection
 Export tests 
 \end_layout
 
@@ -2316,7 +2324,7 @@ status collapsed
  (However, error-free export is no guarantee for an error-free output document.)
 \end_layout
 
-\begin_layout Paragraph
+\begin_layout Subsubsection
 \begin_inset CommandInset label
 LatexCommand label
 name "par:when-to-run-an-export-test"
@@ -2453,7 +2461,7 @@ reference "subsec:Interpreting-export-tests"
 .
 \end_layout
 
-\begin_layout Paragraph
+\begin_layout Subsubsection
 \begin_inset CommandInset label
 LatexCommand label
 name "par:export-test-output-formats"
@@ -2666,7 +2674,7 @@ wordhtml
 \end_layout
 
 \end_deeper
-\begin_layout Paragraph
+\begin_layout Subsubsection
 \begin_inset CommandInset label
 LatexCommand label
 name "par:Configuring-ctests"
@@ -2717,7 +2725,7 @@ reference "subsec:Interpreting-export-tests"
 ).
 \end_layout
 
-\begin_layout Paragraph
+\begin_layout Subsubsection
 \begin_inset CommandInset label
 LatexCommand label
 name "par:ctest-options"
@@ -3047,7 +3055,7 @@ man ctest
 ) the full list of command line options.
 \end_layout
 
-\begin_layout Paragraph
+\begin_layout Subsubsection
 Examples
 \end_layout
 
@@ -3109,7 +3117,7 @@ ctest -L export -E "_(texF|dvi3|pdf3?)"
 
 \end_layout
 
-\begin_layout Paragraph
+\begin_layout Subsubsection
 \begin_inset CommandInset label
 LatexCommand label
 name "subsec:Interpreting-export-tests"
@@ -3332,7 +3340,7 @@ CTestCostData.txt
  file lists the times that it took to run the tests.
 \end_layout
 
-\begin_layout Paragraph
+\begin_layout Subsubsection
 What action should you take if a test fails?
 \end_layout
 
@@ -3460,7 +3468,7 @@ Check the log file Testing/Temporary/LastTest.log.
  to interpret the fail-reason.
 \end_layout
 
-\begin_layout Paragraph
+\begin_layout Subsubsection
 \begin_inset CommandInset label
 LatexCommand label
 name "par:Inverted-tests"
@@ -3609,7 +3617,7 @@ Wontfix
 .
 \end_layout
 
-\begin_layout Subparagraph
+\begin_layout Paragraph
 suspended tests
 \end_layout
 
@@ -3714,7 +3722,7 @@ reference "par:ctest-options"
 ).
 \end_layout
 
-\begin_layout Paragraph
+\begin_layout Subsubsection
 \begin_inset CommandInset label
 LatexCommand label
 name "par:Unreliable-tests"
@@ -3873,7 +3881,7 @@ invalid
 \end_layout
 
 \end_deeper
-\begin_layout Paragraph
+\begin_layout Subsubsection
 \begin_inset CommandInset label
 LatexCommand label
 name "par:Export-test-filtering"
@@ -4892,7 +4900,7 @@ No
 
 \end_layout
 
-\begin_layout Subsubsection
+\begin_layout Subsection
 check_load tests
 \end_layout
 
@@ -4930,7 +4938,7 @@ development/autotests/filterCheckWarnings
 Under cmake, the tests are labeled as 'load'.
 \end_layout
 
-\begin_layout Subsubsection
+\begin_layout Subsection
 Keytests
 \end_layout
 
@@ -4961,7 +4969,7 @@ development/autotests
  source code distribution.
 \end_layout
 
-\begin_layout Subsubsection
+\begin_layout Subsection
 lyx21 tests
 \end_layout
 
@@ -4970,7 +4978,7 @@ These tests combine lyx2lyx tests with check_load tests.
  They fail if either fails.
 \end_layout
 
-\begin_layout Subsubsection
+\begin_layout Subsection
 URL tests
 \end_layout
 
@@ -5007,7 +5015,7 @@ LastTest.log
 'url'.
 \end_layout
 
-\begin_layout Paragraph
+\begin_layout Subsubsection
 Running URL tests
 \end_layout
 
@@ -5052,7 +5060,7 @@ Associated test results can be examined in ctest-log directory in files
  of the form 'LastFailed.*URLS.log'
 \end_layout
 
-\begin_layout Section
+\begin_layout Chapter
 Development policies
 \end_layout
 
@@ -5077,7 +5085,7 @@ reference "sec:When-is-an"
 .
 \end_layout
 
-\begin_layout Subsection
+\begin_layout Section
 When to set a fixed milestone?
 \end_layout
 
@@ -5100,7 +5108,7 @@ If a bug is important, but nobody is working on it, and it is no showstopper,
  For all other bugs, do not set a milestone at all.
 \end_layout
 
-\begin_layout Subsection
+\begin_layout Section
 Can we add rc entries in stable branch?
 \end_layout
 
@@ -5109,7 +5117,7 @@ No.
  We are supposed to increase the prefs2prefs version number with such things.
 \end_layout
 
-\begin_layout Section
+\begin_layout Chapter
 \begin_inset CommandInset label
 LatexCommand label
 name "sec:Documentation-policies"
@@ -5119,7 +5127,7 @@ name "sec:Documentation-policies"
 Documentation policies
 \end_layout
 
-\begin_layout Subsection
+\begin_layout Section
 Rules
 \end_layout
 
@@ -5296,5 +5304,1943 @@ Customization.lyx this manual covers information how to customize \SpecialChar L
  distributions (meaning be as objective as possible).
 \end_layout
 
+\begin_layout Chapter
+Coding rules
+\end_layout
+
+\begin_layout Standard
+The aim of this chapter is to serve as a guide for the developers, to aid
+ us to get clean and uniform code.
+ It is incomplete.
+ We really like to have new developers joining the \SpecialChar LyX
+ Project.
+ However, 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 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.
+\end_layout
+
+\begin_layout Section
+General
+\end_layout
+
+\begin_layout Standard
+These guidelines should save us a lot of work while cleaning up the code
+ and help us to have quality code.
+ \SpecialChar 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 that you:
+\end_layout
+
+\begin_layout Itemize
+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.
+\end_layout
+
+\begin_layout Itemize
+write good C++ code: Readable, well commented and taking advantage of the
+ OO model.
+ Follow the formatting guidelines.
+ See Formatting.
+\end_layout
+
+\begin_layout Itemize
+adapt the code to the structures already existing in \SpecialChar LyX
+, or in the case that
+ you have better ideas, discuss them on the developer's list before writing
+ the code.
+\end_layout
+
+\begin_layout Itemize
+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.
+\end_layout
+
+\begin_layout Itemize
+be aware of exceptions and write exception safe code.
+ See sec.
+\begin_inset space ~
+\end_inset
+
+
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:Exceptions"
+plural "false"
+caps "false"
+noprefix "false"
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Itemize
+document all variables, methods, functions, classes etc.
+ We are using the source documentation program doxygen, a program that handles
+ javadoc syntax, to document sources.
+ You can download doxygen from: 
+\begin_inset Flex URL
+status open
+
+\begin_layout Plain Layout
+
+http://www.stack.nl/~dimitri/doxygen/
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Itemize
+we have certain code constructs that we try to follow.
+ See sec.
+\begin_inset space ~
+\end_inset
+
+
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "sec:Code-constructs"
+plural "false"
+caps "false"
+noprefix "false"
+
+\end_inset
+
+.
+\end_layout
+
+\begin_layout Section
+Submitting code
+\end_layout
+
+\begin_layout Standard
+It is implicitly understood that all patches contributed to The \SpecialChar LyX
+ 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 small)
+ that changes something substantial in \SpecialChar LyX
+.
+ Always discuss your ideas with the developers on the developer's mailing
+ list.
+ When you create the patch, please use "
+\family typewriter
+diff -up
+\family default
+" since we find that a 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 commit message entry with every patch,
+ this describes in detail what the patch is doing.
+ 
+\end_layout
+
+\begin_layout Section
+Code constructs
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:Code-constructs"
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+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++.
+ 
+\end_layout
+
+\begin_layout Itemize
+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.
+ 
+\end_layout
+
+\begin_layout Itemize
+Declare the variable as const if you don't need to change it.
+ This applies to POD types like int as well as classes.
+ 
+\end_layout
+
+\begin_layout Itemize
+Make the scope of a variable as small as possible.
+\end_layout
+
+\begin_layout Itemize
+Make good use of namespaces.
+ Prefer anonymous namespaces to declaring "static" for file scope.
+\end_layout
+
+\begin_layout Itemize
+Prefer preincrement to postincrement whenever possible.
+\end_layout
+
+\begin_layout Itemize
+Preincrement has potential of being faster than postincrement.
+ Just think about the obvious implementations of pre/post-increment.
+ This rule applies to decrement too.
+\end_layout
+
+\begin_layout Itemize
+Use:
+\begin_inset Separator latexpar
+\end_inset
+
+
+\end_layout
+
+\begin_deeper
+\begin_layout Standard
+\begin_inset listings
+lstparams "basicstyle={\footnotesize},language={C++}"
+inline false
+status open
+
+\begin_layout Plain Layout
+
+++T;
+\end_layout
+
+\begin_layout Plain Layout
+
+--U;
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+Do not use:
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+T++; // not used in LyX
+\end_layout
+
+\begin_layout Plain Layout
+
+U--; // not used in LyX
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_deeper
+\begin_layout Itemize
+Try to minimize evaluation of the same code over and over.
+ This is aimed especially at loops.
+ 
+\begin_inset Newline newline
+\end_inset
+
+Use:
+\begin_inset Separator latexpar
+\end_inset
+
+
+\end_layout
+
+\begin_deeper
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+Container::iterator end = large.end();
+\end_layout
+
+\begin_layout Plain Layout
+
+for (Container::iterator it = large.begin(); it != end; ++it) {
+\end_layout
+
+\begin_layout Plain Layout
+
+	...;
+\end_layout
+
+\begin_layout Plain Layout
+
+}
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+Do not use:
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+for (Container::iterator it = large.begin(); it != large.end(); ++it) {
+\end_layout
+
+\begin_layout Plain Layout
+
+	...;
+\end_layout
+
+\begin_layout Plain Layout
+
+}
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_deeper
+\begin_layout Itemize
+For functions and methods that return a non-POD type
+\begin_inset Foot
+status open
+
+\begin_layout Plain Layout
+Plain Ol' Data type
+\end_layout
+
+\end_inset
+
+ T, return T const instead.
+ This gives better type checking, and will give a compiler warning when
+ temporaries are used wrongly.
+\begin_inset Separator latexpar
+\end_inset
+
+
+\end_layout
+
+\begin_deeper
+\begin_layout Standard
+Use:
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+T const add(..);
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+Do not use:
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+T add(..);
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_deeper
+\begin_layout Itemize
+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.
+\end_layout
+
+\begin_layout Itemize
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+enum Foo {
+\end_layout
+
+\begin_layout Plain Layout
+
+	FOO_BAR1,
+\end_layout
+
+\begin_layout Plain Layout
+
+	FOO_BAR2
+\end_layout
+
+\begin_layout Plain Layout
+
+};
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+Foo f = ...;
+\end_layout
+
+\begin_layout Plain Layout
+
+\end_layout
+
+\begin_layout Plain Layout
+
+switch (f) {
+\end_layout
+
+\begin_layout Plain Layout
+
+case FOO_BAR1: ...; 
+\end_layout
+
+\begin_layout Plain Layout
+
+	break;
+\end_layout
+
+\begin_layout Plain Layout
+
+case FOO_BAR2: ...; 
+\end_layout
+
+\begin_layout Plain Layout
+
+	break;
+\end_layout
+
+\begin_layout Plain Layout
+
+default: ...; 
+\end_layout
+
+\begin_layout Plain Layout
+
+	// not needed and would shadow a wrong use of Foo
+\end_layout
+
+\begin_layout Plain Layout
+
+	break; 
+\end_layout
+
+\begin_layout Plain Layout
+
+}
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Section
+Exceptions
+\begin_inset CommandInset label
+LatexCommand label
+name "sec:Exceptions"
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+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 
+\begin_inset CommandInset citation
+LatexCommand cite
+key "sutter"
+literal "false"
+
+\end_inset
+
+):
+\end_layout
+
+\begin_layout Enumerate
+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.
+ 
+\end_layout
+
+\begin_layout Enumerate
+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: 
+\begin_inset Flex URL
+status open
+
+\begin_layout Plain Layout
+
+http://www.stlport.org/doc/exception_safety.html
+\end_layout
+
+\end_inset
+
+ 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 or 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:
+\end_layout
+
+\begin_layout Enumerate
+No throw guarantee: The function will not emit an exception under any circumstan
+ces.
+ 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 
+\family typewriter
+Swap()
+\family default
+.
+\end_layout
+
+\begin_layout Standard
+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.
+\end_layout
+
+\begin_layout Section
+Formatting
+\end_layout
+
+\begin_layout Itemize
+Only one declaration on each line.
+\begin_inset Separator latexpar
+\end_inset
+
+
+\end_layout
+
+\begin_deeper
+\begin_layout Standard
+Use:
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+int a;
+\end_layout
+
+\begin_layout Plain Layout
+
+int b;
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+Do not use:
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+int a, b; // not used in LyX
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+This is especially important when initialization is done at the same time:
+\end_layout
+
+\begin_layout Standard
+Use:
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+string a = "Lars";
+\end_layout
+
+\begin_layout Plain Layout
+
+string b = "Gullik";
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+Do not use:
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+string a = "Lars", b = "Gullik"; // not used in LyX
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+[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, \SpecialChar 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 initializati
+ons.]
+\end_layout
+
+\end_deeper
+\begin_layout Itemize
+Pointers and references:
+\begin_inset Separator latexpar
+\end_inset
+
+
+\end_layout
+
+\begin_deeper
+\begin_layout Standard
+Use:
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+char * p = "flop";
+\end_layout
+
+\begin_layout Plain Layout
+
+char & c = *p;
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+Do not use:
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+char *p = "flop"; // not used in LyX
+\end_layout
+
+\begin_layout Plain Layout
+
+char &c = *p; // not used in LyX
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+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:
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+char const * p;
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+and not
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+const char * p; // not used in LyX
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_deeper
+\begin_layout Itemize
+Operator names and parentheses
+\begin_inset Separator latexpar
+\end_inset
+
+
+\end_layout
+
+\begin_deeper
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+operator==(type)
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+and not
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+operator == (type) // not used in LyX
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+The == is part of the function name, separating it makes the declaration
+ look like an expression.
+\end_layout
+
+\end_deeper
+\begin_layout Itemize
+Function names and parentheses
+\begin_inset Separator latexpar
+\end_inset
+
+
+\end_layout
+
+\begin_deeper
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+void mangle()
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+and not
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+void mangle () // not used in LyX
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_deeper
+\begin_layout Itemize
+Enumerators
+\begin_inset Separator latexpar
+\end_inset
+
+
+\end_layout
+
+\begin_deeper
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+enum Foo {
+\end_layout
+
+\begin_layout Plain Layout
+
+	FOO_ONE = 1,
+\end_layout
+
+\begin_layout Plain Layout
+
+	FOO_TWO = 2,
+\end_layout
+
+\begin_layout Plain Layout
+
+	FOO_THREE = 3
+\end_layout
+
+\begin_layout Plain Layout
+
+};
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+and not
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+enum { one = 1, two = 2, three 3 }; // not used in LyX
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+and not
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+enum {
+\end_layout
+
+\begin_layout Plain Layout
+
+One = 1,
+\end_layout
+
+\begin_layout Plain Layout
+
+Two = 2,
+\end_layout
+
+\begin_layout Plain Layout
+
+Three = 3
+\end_layout
+
+\begin_layout Plain Layout
+
+};
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_deeper
+\begin_layout Itemize
+Null pointers
+\begin_inset Separator latexpar
+\end_inset
+
+
+\end_layout
+
+\begin_deeper
+\begin_layout Standard
+Using a plain 0 is always correct and least effort to type.
+ So: 
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+void * p = 0;
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+and not
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+void * p = NULL; // not used in LyX
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+and not
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+void * p = '
+\backslash
+0'; // not used in LyX
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+and not
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+void * p = 42 - 7 * 6; // not used in LyX
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+Note: As an exception, imported third party code as well as code interfacing
+ the "native" APIs (src/support/os_*) can use NULL.
+\end_layout
+
+\end_deeper
+\begin_layout Itemize
+Naming rules for classes
+\begin_inset Separator latexpar
+\end_inset
+
+
+\end_layout
+
+\begin_deeper
+\begin_layout Itemize
+Use descriptive but simple and short names.
+ Do not abbreviate.
+\end_layout
+
+\begin_layout Itemize
+Class names are usually capitalized, and function names lowercased.
+\end_layout
+
+\begin_layout Itemize
+Enums are named like Classes, values are usually in lower-case.
+\end_layout
+
+\begin_layout Itemize
+Public API is camel-case ('
+\family typewriter
+void setAFlagToAValue(bool)
+\family default
+')
+\end_layout
+
+\begin_layout Itemize
+Members variables are underscored ('
+\family typewriter
+enable_this_feature_flag_
+\family default
+') with a final '
+\family typewriter
+_
+\family default
+'
+\end_layout
+
+\begin_layout Itemize
+Private/protected functions are also camel-case
+\end_layout
+
+\begin_layout Itemize
+New types are capitalized, so this goes for typedefs, classes, structs and
+ enums.
+\end_layout
+
+\end_deeper
+\begin_layout Itemize
+Formatting
+\begin_inset Separator latexpar
+\end_inset
+
+
+\end_layout
+
+\begin_deeper
+\begin_layout Itemize
+Adapt the formatting of your code to the one used in the other parts of
+ \SpecialChar LyX
+.
+ In case there is different formatting for the same construct, use the one
+ used more often.
+\end_layout
+
+\end_deeper
+\begin_layout Itemize
+Use existing structures
+\begin_inset Separator latexpar
+\end_inset
+
+
+\end_layout
+
+\begin_deeper
+\begin_layout Itemize
+\begin_inset CommandInset label
+LatexCommand label
+name "Use-string-wherever"
+
+\end_inset
+
+Use string wherever possible.
+ \SpecialChar LyX
+ will someday move to Unicode, and that will be easy if everybody uses
+ string now.
+ Unicode strings should prefer using docstring instead of UTF-8 encoded
+ std::string.
+\end_layout
+
+\begin_layout Itemize
+Check out the filename and path tools in filetools.h
+\end_layout
+
+\begin_layout Itemize
+Check out the string tools in lstring.h.
+\end_layout
+
+\begin_layout Itemize
+Use the \SpecialChar LyX
+Err class to report errors and messages using the lyxerr instantiation.
+ [add description of other existing structures]
+\end_layout
+
+\end_deeper
+\begin_layout Itemize
+Declarations
+\begin_inset Separator latexpar
+\end_inset
+
+
+\end_layout
+
+\begin_deeper
+\begin_layout Itemize
+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]
+\end_layout
+
+\begin_layout Itemize
+Avoid declaring global objects in the declaration file of the class.
+ If the same variable is used for all objects, use a static member.
+\end_layout
+
+\begin_layout Itemize
+Avoid global or static variables.
+\end_layout
+
+\end_deeper
+\begin_layout Itemize
+File headers
+\begin_inset Separator latexpar
+\end_inset
+
+
+\end_layout
+
+\begin_deeper
+\begin_layout Standard
+If you create a new file, the top of the file should look something like
+ this :
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+/**
+\end_layout
+
+\begin_layout Plain Layout
+
+* 
+\backslash
+file NewFile.cpp
+\end_layout
+
+\begin_layout Plain Layout
+
+* This file is part of LyX, the document processor.
+\end_layout
+
+\begin_layout Plain Layout
+
+* Licence details can be found in the file COPYING.
+\end_layout
+
+\begin_layout Plain Layout
+
+*
+\end_layout
+
+\begin_layout Plain Layout
+
+* 
+\backslash
+author Kaiser Sose
+\end_layout
+
+\begin_layout Plain Layout
+
+*
+\end_layout
+
+\begin_layout Plain Layout
+
+* Full author contact details are available in file CREDITS
+\end_layout
+
+\begin_layout Plain Layout
+
+*/
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_deeper
+\begin_layout Itemize
+Documentation
+\begin_inset Separator latexpar
+\end_inset
+
+
+\end_layout
+
+\begin_deeper
+\begin_layout Itemize
+The documentation is generated from the header files.
+\end_layout
+
+\begin_layout Itemize
+You document for the other developers, not for yourself.
+\end_layout
+
+\begin_layout Itemize
+You should document what the function does, not the implementation.
+\begin_inset Separator latexpar
+\end_inset
+
+
+\end_layout
+
+\begin_deeper
+\begin_layout Itemize
+in the .cpp files you document the implementation.
+\end_layout
+
+\end_deeper
+\begin_layout Itemize
+Single line description (///), multiple lines description (/** ...
+ */) see the doxygen webpage referenced above
+\end_layout
+
+\end_deeper
+\begin_layout Section
+Naming rules for Lyx User Functions (LFUNs)
+\end_layout
+
+\begin_layout Standard
+Here is the set of rules to apply when a new command name is introduced:
+\end_layout
+
+\begin_layout Enumerate
+Use the object.event order.
+ That is, use `word-forward' instead of`forward-word'.
+\end_layout
+
+\begin_layout Enumerate
+Don't introduce an alias for an already named object.
+ Same for events.
+\end_layout
+
+\begin_layout Enumerate
+Forward movement or focus is called `forward' (not `right').
+\end_layout
+
+\begin_layout Enumerate
+Backward movement or focus is called `backward' (not `left').
+\end_layout
+
+\begin_layout Enumerate
+Upward movement of focus is called `up'.
+\end_layout
+
+\begin_layout Enumerate
+Downward movement is called `down'.
+\end_layout
+
+\begin_layout Enumerate
+The begin of an object is called `begin' (not `start').
+\end_layout
+
+\begin_layout Enumerate
+The end of an object is called `end'.
+\end_layout
+
+\begin_layout Section
+How to create class interfaces
+\end_layout
+
+\begin_layout Standard
+(a.k.a How Non-Member Functions Improve Encapsulation)
+\end_layout
+
+\begin_layout Standard
+I recently read an article by Scott Meyers, where he makes a strong case
+ on how non-member functions makes classes more encapsulated, not less.
+ Just skipping to the core of this provides us with the following algorithm
+ for deciding what kind of function to add to a class interface:
+\end_layout
+
+\begin_layout Itemize
+We need to add a function f to the class C's API.
+\begin_inset Separator latexpar
+\end_inset
+
+
+\end_layout
+
+\begin_deeper
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+if (f needs to be virtual)
+\end_layout
+
+\begin_layout Plain Layout
+
+	make f a member function of C;
+\end_layout
+
+\begin_layout Plain Layout
+
+else if (f is operator>> or operator<<) {
+\end_layout
+
+\begin_layout Plain Layout
+
+	make f a non-member function;
+\end_layout
+
+\begin_layout Plain Layout
+
+	if (f needs access to non-public members of C)
+\end_layout
+
+\begin_layout Plain Layout
+
+		make f a friend of C;
+\end_layout
+
+\begin_layout Plain Layout
+
+} else if (f needs type conversions on its left-most argument) {
+\end_layout
+
+\begin_layout Plain Layout
+
+	make f a non-member function;
+\end_layout
+
+\begin_layout Plain Layout
+
+	if (f needs access to non-public members of C)
+\end_layout
+
+\begin_layout Plain Layout
+
+		make f a friend of C;
+\end_layout
+
+\begin_layout Plain Layout
+
+} else if (f can be implemented via C's public interface)
+\end_layout
+
+\begin_layout Plain Layout
+
+	make f a non-member function;
+\end_layout
+
+\begin_layout Plain Layout
+
+else
+\end_layout
+
+\begin_layout Plain Layout
+
+	make f a member function of C;
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\end_deeper
+\begin_layout Chapter
+Coding recommendations
+\end_layout
+
+\begin_layout Standard
+These are some rules for effective C++ programming.
+ These are taken from Scott Meyers 
+\begin_inset CommandInset citation
+LatexCommand cite
+key "journal"
+literal "true"
+
+\end_inset
+
+, and are presented in their short form.
+ These are not all the rules Meyers presents, only the most important of
+ them.
+ \SpecialChar LyX
+ does not yet follow these rules, but they should be the goal.
+\end_layout
+
+\begin_layout Itemize
+use 
+\family typewriter
+const
+\family default
+ and 
+\family typewriter
+inline
+\family default
+ instead of 
+\family typewriter
+#define
+\end_layout
+
+\begin_layout Itemize
+use the same form in corresponding calls to new and delete, i.e.
+ write delete[] obj; if new obj[n]; was used to create the object and write
+ delete obj; if you wrote new obj; Notice strings should be std::string's
+ instead of char *'s.
+ (this contradicts to 
+\begin_inset CommandInset ref
+LatexCommand ref
+reference "Use-string-wherever"
+
+\end_inset
+
+ )
+\end_layout
+
+\begin_layout Itemize
+define a default constructor, copy constructor and an assignment operator
+ for all classes with dynamically allocated memory that are not made noncopyable
+\end_layout
+
+\begin_layout Itemize
+do not define default constructor, copy constructor and an assignment operator
+ if the compiler generated one would do the same
+\end_layout
+
+\begin_layout Itemize
+make destructors virtual in base classes and only there 
+\end_layout
+
+\begin_layout Itemize
+assign to all data members in operator=()
+\end_layout
+
+\begin_layout Itemize
+strive for class interfaces that are complete and minimal
+\end_layout
+
+\begin_layout Itemize
+differentiate among member functions, global functions and friend functions
+\end_layout
+
+\begin_layout Itemize
+avoid data members in the public interface
+\end_layout
+
+\begin_layout Itemize
+use const whenever possible
+\end_layout
+
+\begin_layout Itemize
+pass and return objects by reference instead of by value
+\end_layout
+
+\begin_layout Itemize
+choose carefully between function overloading and parameter defaulting
+\end_layout
+
+\begin_layout Itemize
+never return a reference to a local object or a dereferenced pointer initialized
+ by new within the function
+\end_layout
+
+\begin_layout Itemize
+use enums for integral constants
+\end_layout
+
+\begin_layout Itemize
+minimize compilation dependencies between files
+\end_layout
+
+\begin_layout Itemize
+pay attention to compiler warnings
+\end_layout
+
+\begin_layout Itemize
+differentiate between inheritance of interface and inheritance of implementation
+\end_layout
+
+\begin_layout Itemize
+differentiate between inheritance and templates
+\end_layout
+
+\begin_layout Itemize
+ensure that global objects are initialized before they are used
+\end_layout
+
+\begin_layout Itemize
+avoid conditions to 'if' and 'while' that span more than a line
+\end_layout
+
+\begin_layout Chapter
+\start_of_appendix
+Notes
+\end_layout
+
+\begin_layout Itemize
+And one of mine: (Lgb)
+\begin_inset Separator latexpar
+\end_inset
+
+
+\end_layout
+
+\begin_deeper
+\begin_layout Itemize
+when switching on enums, refrain from using "default:" if possible
+\end_layout
+
+\end_deeper
+\begin_layout Itemize
+And one of mine: (Andre')
+\begin_inset Separator latexpar
+\end_inset
+
+
+\end_layout
+
+\begin_deeper
+\begin_layout Itemize
+try to implement your class in a way that the automatically generated copy
+ constructor and copy assignment work out-of-the box
+\end_layout
+
+\begin_layout Itemize
+I don't have problems with using boost in the implementation _if and only
+ if_ it provides actual benefits over less intrusive alternatives.
+ I do have a problem with needlessly sprinkling 'boost::' over interfaces,
+ especially if it does not add any value.
+\begin_inset Separator latexpar
+\end_inset
+
+
+\end_layout
+
+\begin_deeper
+\begin_layout Standard
+Given that there seems to be an unconditional "typedef unsigned int quint32;"
+ in qglobal.h I don't think there's any platform supported by current \SpecialChar LyX
+ that
+ could not use 'unsigned int' (and an static assert in some implementation
+ file for the unlikely case some ILP64 zombie raises its ugly head again.
+ And if that happens, using <cstdint> would still be a better choice...)
+\end_layout
+
+\begin_layout Standard
+The idea is to create something that's not compilable as soon as the condition
+ is violated.
+ There are lots of possibilities to achieve this, some examples follow:
+\end_layout
+
+\begin_layout Standard
+In C++0x there's a "built-in":
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+static_assert(sizeof(int) == 4, "Funny platform")
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+until then on namespace scope: 
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+#include <boost/static_assert.hpp> BOOST_STATIC_ASSERT(sizeof(int) == 4)
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+or without boost:
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+template<bool Condition> struct static_assert_helper;
+\end_layout
+
+\begin_layout Plain Layout
+
+template <> struct static_assert_helper<true> {}; 
+\end_layout
+
+\begin_layout Plain Layout
+
+enum { dummy = sizeof(static_assert_helper<sizeof(int) == 4>)};
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+or somewhat brutish without templates, in any function:
+\end_layout
+
+\begin_layout Standard
+\begin_inset listings
+inline false
+status open
+
+\begin_layout Plain Layout
+
+const int d = sizeof(int) - 4;
+\end_layout
+
+\begin_layout Plain Layout
+
+switch(0) { 
+\end_layout
+
+\begin_layout Plain Layout
+
+case 0: 
+\end_layout
+
+\begin_layout Plain Layout
+
+case !(d*d): 
+\end_layout
+
+\begin_layout Plain Layout
+
+break; 
+\end_layout
+
+\begin_layout Plain Layout
+
+}
+\end_layout
+
+\end_inset
+
+
+\end_layout
+
+\begin_layout Standard
+Any of them in a .cpp file will break compilation as soon as sizeof(int)
+ is not equal 4.
+ Personally I prefer something like the third version (or the first, if
+ using C++0x is allowed).
+\end_layout
+
+\end_deeper
+\end_deeper
+\begin_layout Itemize
+And one of mine: (vfr)
+\begin_inset Separator latexpar
+\end_inset
+
+
+\end_layout
+
+\begin_deeper
+\begin_layout Itemize
+On dynamics_casts 
+\begin_inset Flex URL
+status open
+
+\begin_layout Plain Layout
+
+http://www.lyx.org/trac/changeset/35855
+\end_layout
+
+\end_inset
+
+:
+\begin_inset Separator latexpar
+\end_inset
+
+
+\end_layout
+
+\begin_deeper
+\begin_layout Standard
+A dynamic_cast is necessary when:
+\end_layout
+
+\begin_layout Itemize
+the object to be casted is from an external library because we can't add
+ Qxxx::asXxxx() to Qt e.g.:
+\begin_inset Separator latexpar
+\end_inset
+
+
+\end_layout
+
+\begin_deeper
+\begin_layout Itemize
+QAbstractListModel to GuiIdListModel,
+\end_layout
+
+\begin_layout Itemize
+QValidator to PathValidator,
+\end_layout
+
+\begin_layout Itemize
+QWidget to TabWorkArea,
+\end_layout
+
+\begin_layout Itemize
+QWidget to GuiWorkArea;
+\end_layout
+
+\end_deeper
+\begin_layout Itemize
+the object is to be casted from an interface to the implementing class,
+ because the Interface does not know by whom it is implemented:
+\begin_inset Separator latexpar
+\end_inset
+
+
+\end_layout
+
+\begin_deeper
+\begin_layout Itemize
+ProgressInterface to GuiProgress,
+\end_layout
+
+\begin_layout Itemize
+Application to GuiApplication.
+\end_layout
+
+\end_deeper
+\begin_layout Standard
+A dynamic_cast can be replaced by:
+\end_layout
+
+\begin_layout Itemize
+already existing as***Inset() functions, e.g.:
+\begin_inset Separator latexpar
+\end_inset
+
+
+\end_layout
+
+\begin_deeper
+\begin_layout Itemize
+asHullInset(),
+\end_layout
+
+\begin_layout Itemize
+asInsetMath()->asMacro(),
+\end_layout
+
+\begin_layout Itemize
+asInsetText();
+\end_layout
+
+\end_deeper
+\begin_layout Itemize
+A static_cast when we are sure this can't go wrong, e.g.:
+\begin_inset Separator latexpar
+\end_inset
+
+
+\end_layout
+
+\begin_deeper
+\begin_layout Itemize
+we are sure that CellData::inset->clone() is an InsetTableCell,
+\end_layout
+
+\begin_layout Itemize
+in cases where we explicitly check it->lyxCode().
+\end_layout
+
+\end_deeper
+\end_deeper
+\end_deeper
+\begin_layout Bibliography
+\begin_inset CommandInset bibitem
+LatexCommand bibitem
+key "meyers"
+literal "true"
+
+\end_inset
+
+S.
+ Meyers.
+ Effective C++, 50 Specific Ways to Improve Your Programs and Design.
+ Addison-Wesley, 1992
+\end_layout
+
+\begin_layout Bibliography
+\begin_inset CommandInset bibitem
+LatexCommand bibitem
+key "sutter"
+literal "true"
+
+\end_inset
+
+Sutter, Herb.
+ Exceptional C++: 47 engineering puzzles, programming problems, and solutions.
+ ISBN 0-201-61562-2
+\end_layout
+
+\begin_layout Bibliography
+\begin_inset CommandInset bibitem
+LatexCommand bibitem
+key "journal"
+literal "true"
+
+\end_inset
+
+Scott Meyers, C/C++ User's Journal (Vol.18,No.2)
+\end_layout
+
 \end_body
 \end_document
-- 
2.28.0.windows.1