Fill 'framework' paragraph

doc/userdoc.org

@@ -262,22 +262,64 @@ of code acts as a pure function (arguments are unchanged by calls),
 the context is quite easily checked.
 
 Finally it aims at simplifying the definition of new methods since
-common utilities are available directly in simple scipts.
-
-**** TODO The framework (divide and conquer)
-
-- small independent C++ methods
-  - easy to test/validate
-  - do simple things the right way
-- new numerical method brings a new C++ code: not a patched code.
-  A previously validated method is unchanged!
-  - much more difficult to introduce bugs in existing methods
-  - existing methods performances are likely to be unchanged by new
-    developments
-- utilities are not developed again and again:
-  - safer code
-  - important code is not polluted by environment instructions (data
-    initialization, error calculation, post-processing,...)
+common utilities are available directly in scripts.
+
+**** The framework: divide and conquer
+
+~pugs~ is a research oriented software, thus generally the user is also
+a developer. If this paragraph is indeed more dedicated to the
+developer, reading it, the user will understand better the choices and
+policy that drive the code.
+
+Actually the development framework imposed by the DSL tends to guide
+writing of new methods.
+
+- A natural consequence is that the developer is encourage to write
+  small independent ~C++~ methods (even it does not forbid to write big
+  monolithic pieces of code). However as already said, one should try
+  to respect the following precept: write small piece of code to ease
+  their testing and validation, try to do simple things the right way.
+- Also, in the process of writing a *new numerical methods*, one must
+  create *new functions in the language*. Moreover, if a new method is
+  close to an existing one, it is generally *better* to use completely
+  new underlying ~C++~ code than to patch existing methods. Starting
+  from a *copy* of the existing code is *encouraged* for
+  developments. This may sound weird since classical development
+  guidelines encourage inheritance or early redesign. Actually, this
+  policy is the result of the following discussion.
+  - Using this approach, one *separates* clearly the *design* of a
+    numerical method and the *design* of the code!
+  - From the computer science point of view, early design for new
+    numerical methods is generally wrong: usually one cannot
+    anticipate precisely enough eventual problems or method
+    corrections.
+  - It is much more difficult to introduce bugs in existing methods,
+    since previously validated methods are unchanged!
+  - For the same reason, existing methods performances are naturally
+    unchanged by new developments.
+  - Also, when comparing methods, it is better to compare to the
+    original existing code.
+  - If the new method is abandoned or simply not kept, the existing
+    code is not polluted.
+  - Finally when a method is validated and ready to integrate the
+    mainline of the code, it is easier to see differences with
+    existing ones and *at this time* one can redesign the ~C++~ code
+    checking that results are unchanged and performances not
+    deteriorated. At this time, it is likely that the numerical method
+    design if finished, thus (re)designing the code makes more sense.
+- Another consequence is that utilities are not be developed again and
+  again.
+  - This implies an /a priori/ safer code: utilities are well tested and
+    validated.
+  - It saves development time obviously.
+  - Numerical methods code is not polluted by environment instructions
+    (data initialization, error calculation, post-processing,...)
+  - The counterpart is somehow classical. In the one hand, the
+    knowledge of existing utilities is required, this document tries
+    to address a part of it. In the other hand, if the developer
+    requires a new utility, a good practice is to discuss with the
+    others to check if it could benefit to the others to determine if
+    it should integrate rapidly or not the main development branch.
 
 **** TODO Why not python or any other scripting language?