Coding conventions

docs/source/programmers_guide/conventions.rst

@@ -0,0 +1,98 @@
+==================
+Coding conventions
+==================
+
+
+General conventions
+===================
+
+All executable files should have a name with lowercase.
+
+Tabs are forbidden everywhere.
+
+Try to set the maximum line length to 80 characters.  Long lines can be
+automatically reformatted in vim by pressing :kbd:`gqj`.
+
+Use blank lines between blocks to improve readability.
+
+For existing files, stay faithful to the existing indentation.
+
+
+
+Shell scripts
+=============
+
+Executables should have no extension.  To know if the file is binary, or in
+what shell scripting language it was written, the :command:`file` command can
+be used. In addition, all the shell scripts should be under
+:file:`${QP_ROOT}/scripts/`.
+
+The exit code of the script should be 0 upon success only.
+
+Bash and Python2 are the only shell scripting language permitted for
+executables.
+
+
+Bash
+----
+
+* Bash scripts should start with ``#!/bin/bash``
+
+* All error messages should go to standard error, and should be prefixed with
+  the name of the command. For example, in Bash use
+
+  .. code:: bash
+
+      function echo_err() {
+         2>& echo $(basename $0)": error"
+      }
+
+* The command-line options should be handled with ``getopt``.
+
+* The script should check that the command-line arguments are consistent.
+
+* Long options should be preferred to short options.
+
+* Always quote strings containing variables, command substitutions, spaces or
+  shell meta characters, unless careful unquoted expansion is required.
+
+* Use ``"$@"`` unless you have a specific reason to use ``$*``.
+
+* Use ``$(command)`` instead of backticks, because they can be easily nested.
+
+* ``[[ ... ]]`` is preferred over ``[``, ``test`` and ``/usr/bin/[``.
+
+* Declare function-specific variables with local. Declaration and assignment
+  should be on different lines.
+
+* Pipelines should be split one per line if they don't all fit on one line.
+
+* Put ``; do`` and ``; then`` on the same line as the ``while``, ``for`` or ``if``.
+
+
+Python
+------
+
+Only Python2 is supported. The reason is that some dependencies use Python2,
+and we do not want yet to add an extra dependency to Python3. 
+
+Python scripts should start with ``#!/usr/bin/env python2`` to mention
+explicitly that Python2 has to be used.
+
+:command:`pylint` should be used to increase the quality of the source code.
+
+
+
+IRPF90
+======
+
+The code can be automatically indented with :command:`irp_indent`.
+
+Mathematical formulas in the `BEGIN_DOC...END_DOC` sections sould be written
+in LaTeX format, between `$` symbols.
+
+Providers should never be present in the same file as a main program.
+
+
+
+

etc/autocomplete.rc

@@ -0,0 +1,8 @@
+# Required for completion with zsh
+
+if [[ "$(ps -p $$ -ocomm=)" == "zsh" ]] ; then
+  autoload bashcompinit
+  bashcompinit
+fi
+
+