Initial document layout for coding conventions.

Jürgen Knödlseder
1 parent 430c2b2c
Showing 7 changed files with 128 additions and 6 deletions
doc/source/_templates/index.html
doc/source/coding/cpp.rst
doc/source/coding/general.rst
doc/source/coding/index.rst
doc/source/coding/introduction.rst
doc/source/coding/python.rst
doc/source/contents.rst
@@ -52,6 +52,7 @@ and next steps, and advance with the coding of the software. {%endtrans%}&lt;/p&gt;
 <li><a class="smalllink" href="{{ pathto("reference_manual/index") }}">{%trans%}Reference Manual{%endtrans%}</a></li> 
 <li><a class="smalllink" href="{{ pathto("faq") }}">{%trans%}Frequently asked questions{%endtrans%}</a></li> 
 <li><a class="smalllink" href="{{ pathto("issues") }}">{%trans%}Known issues{%endtrans%}</a></li> 
+<li><a class="smalllink" href="{{ pathto("coding/index") }}">{%trans%}Coding conventions{%endtrans%}</a></li> 
 <li><a class="smalllink" href="doxygen/index.html">{%trans%}Source code documentation (Doxygen){%endtrans%}</a></li> 
 </ul>
  
+C++ coding rules
+================
+
+All ctools C++ code must be compatible with ISO standard C++98. Do not
+use C++11 features (see `here <http://en.wikipedia.org/wiki/C%2B%2B#Standardization>`__
+if you don't know what C++98 and C++11 is and note that C++03 is just
+a minor correction of C++98).
+
+The reason for this restriction is that C++ compilers / standard libraries
+such as `gcc <http://gcc.gnu.org>`_ / `libstdc++ <http://gcc.gnu.org/libstdc++/>`_
+or `clang <http://clang.llvm.org>`_ / `libc++ <http://libcxx.llvm.org>`_
+only finished implementing C++11 in 2013 and using C++11 features in
+ctools would make it impossible to use the code on many systems.
+
+
+Code lay-out
+^^^^^^^^^^^^
+
+String quotes
+^^^^^^^^^^^^^
+
+Whitespace in Expressions and Statements
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Comments
+^^^^^^^^
+
+Naming Conventions
+^^^^^^^^^^^^^^^^^^                                
+
+Programming Recommendations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+General rules
+=============
+
+Code lay-out
+^^^^^^^^^^^^
+
+- Use 4 spaces per indentation level
+
+- Do not use tabs
+
+- Do not exceed a line length of 80 characters (a few more characters
+  are acceptable in exceptional cases)
+
+- Put a blank line at the end of each file (this is required by some
+  compilers)
+
+- Align successive similar lines on common elements. Here an example
+  illustrating the alignment on the ``=`` symbol:
+
+  .. code-block:: python
+
+     max     = par.max
+     prompt  = par.prompt
+     sum    += par.sum
+
+- Each function or method must terminate with a single return statement
+  that is placed at the end
+Coding and Design Conventions
+=============================
+
+.. toctree::
+   :maxdepth: 2
+
+   introduction
+   general
+   python
+   cpp
+
+Introduction
+============
+
+This document gives the coding conventions for the ctools software
+package.
+
+The coding conventions shall be followed by all developers who intend
+to commit code to ctools.
+
+Respecting uniform and coherent coding conventions is crucial for
+software development. They improve code readability, ease code
+development and maintenance, ensure code portability, and provide
+standards for the user interface.
+
+The coding conventions for ctools were inspired by a large survey of
+existing C++ coding rules and the Style Guide for Python Code (PEP-0008),
+combined with the experience of the leading code developers. Obviously,
+there is no single best way to code in Python and C++, and the adopted
+conventions may not meet your style of coding. The ctools coding rules
+should nevertheless be respected, and if violated, you should have good
+reasons for that.
+Python coding rules
+===================
+
+The Python coding rules have been inspired from the Style Guide for
+Python Code `PEP 0008 <http://www.python.org/dev/peps/pep-0008/>`_.
+You can check whether you code complies to these rules using the
+`pep8 tool <https://github.com/jcrocholl/pep8>`_ that you should run
+on your Python code before committing.
+
+All ctools code must be compatible with Python 2.3 or higher, and
+Python 3.0 and higher. No Python modules that are not available in
+these Python version shall be used.
+
+
+Code lay-out
+^^^^^^^^^^^^
+
+String quotes
+^^^^^^^^^^^^^
+
+Whitespace in Expressions and Statements
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Comments
+^^^^^^^^
+
+Naming Conventions
+^^^^^^^^^^^^^^^^^^
+
+Programming Recommendations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
-.. ctools documentation master file, created by
-   sphinx-quickstart on Sat Apr 13 16:41:07 2013.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 Documentation
 =============
  
@@ -16,4 +11,5 @@ Documentation
    faq
    issues
    develop
-   help
 \ No newline at end of file
+   coding/index
+   help