Merge branch '1742-coding-conventions' into integration

# Conflicts: # cscripts/cscaldb.py

Merge branch '1742-coding-conventions' into integration
# Conflicts: # cscripts/cscaldb.py
Jürgen Knödlseder
2 parents 1f4ac933 a8093c0a
Showing 8 changed files with 645 additions and 56 deletions
cscripts/cscaldb.py
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
 #! /usr/bin/env python
 # ==========================================================================
-# This script dumps all available calibrations into the console.
+# Show the content of the ctools calibration database
 #
 # Copyright (C) 2014-2016 Juergen Knoedlseder
 #
@@ -32,19 +32,30 @@ class cscaldb(ctools.cscript):
     """
     Shows the content of the ctools calibration database.
  
-    If the "debug" parameter is set to "yes" the calibration database
-    is shown in the console, otherwise the content is only written
-    into the "cscaldb.log" log file.
+    The ``cscaldb`` script writes the content of the calibration database
+    into the ``cscaldb.log`` log file. If the ``debug`` parameter is set
+    to ``yes`` the calibration database is also logged in the console.
     """
  
     # Constructor
     def __init__(self, *argv):
         """
         Constructor.
+        
+        Parameters
+        ----------
+        argv : list of str
+            List of IRAF command line parameter strings of the form
+            ``parameter=3``.
+
+        Raises
+        ------
+        TypeError
+            An invalid number of command line arguments was provided.
         """
         # Set name
-        self._name    = "cscaldb"
-        self._version = "1.1.0"
+        self._name    = 'cscaldb'
+        self._version = '1.1.0'
  
         # Initialise application by calling the appropriate class
         # constructor.
@@ -55,33 +66,26 @@ class cscaldb(ctools.cscript):
  
  
     # Private methods
+    #
+    # Query all user parameters
     def _get_parameters(self):
-        """
-        Get parameters from parfile.
-        """
+
         #  Write input parameters into logger
         if self._logTerse():
             self._log_parameters()
-            self._log("\n")
+            self._log('\n')
  
         # Return
         return
  
+    # Extract mission names from a calibration database
     def _get_missions(self, caldb):
-        """
-        Extract mission names from a calibration database.
-
-        Args:
-            caldb: Calibration database.
  
-        Returns:
-            A list of mission names.
-        """
         # Initialise mission list
         missions = []
  
         # Extract missions
-        paths = glob.glob(caldb.rootdir()+"/data/*")
+        paths = glob.glob(caldb.rootdir()+'/data/*')
         paths.sort()
         for path in paths:
             missions.append(os.path.basename(path))
@@ -92,22 +96,14 @@ class cscaldb(ctools.cscript):
         # Return missions
         return missions
  
+    # Extract instrument names from a calibration database
     def _get_instruments(self, caldb, mission):
-        """
-        Extract instrument names from a calibration database.
-
-        Args:
-            caldb:   Calibration database.
-            mission: Mission name.
  
-        Returns:
-            A list of instrument names.
-        """
         # Initialise instrument list
         instruments = []
  
         # Extract instruments
-        paths       = glob.glob(caldb.rootdir()+"/data/"+mission+"/*")
+        paths       = glob.glob(caldb.rootdir()+'/data/'+mission+'/*')
         paths.sort()
         for path in paths:
             instruments.append(os.path.basename(path))
@@ -118,17 +114,10 @@ class cscaldb(ctools.cscript):
         # Return instruments
         return instruments
  
+    # Extract response names from a calibrations FITS table and return them
+    # in form of a list
     def _get_response_names(self, calibrations):
-        """
-        Extract response names from a calibrations FITS table and return
-        them in form of a list.
-
-        Args:
-            calibrations: FITS table containing the calibrations.
  
-        Returns:
-            A list of response names.
-        """
         # Initialise response name list
         names = []
  
@@ -139,9 +128,9 @@ class cscaldb(ctools.cscript):
         for row in range(nrows):
             for col in range(ncols):
                 cal    = calibrations.string(row, col)
-                istart = cal.find("NAME(")
+                istart = cal.find('NAME(')
                 if istart != -1:
-                    istop = cal.find(")")
+                    istop = cal.find(')')
                     name  = cal[5:istop]
                     if names.count(name) == 0:
                         names.append(name)
@@ -175,13 +164,13 @@ class cscaldb(ctools.cscript):
         for mission in missions:
  
             # Skip all non-CTA instruments
-            if mission != "cta":
+            if mission != 'cta':
                 continue
  
             # Write mission into logger
             if self._logTerse():
-                self._log("\n")
-                self._log.header1("Mission: "+mission)
+                self._log('\n')
+                self._log.header1('Mission: '+mission)
  
             # Extract instruments
             instruments = self._get_instruments(caldb, mission)
@@ -191,15 +180,15 @@ class cscaldb(ctools.cscript):
  
                 # Write mission into logger
                 if self._logTerse():
-                    self._log.header3("Response functions in database \""+
-                                      instrument+"\"")
+                    self._log.header3('Response functions in database "'+
+                                      instrument+'"')
  
                 # Open calibration index file and retrieve calibrations
-                filename = "/data/"+mission+"/"+instrument+"/caldb.indx"
+                filename = '/data/'+mission+'/'+instrument+'/caldb.indx'
                 cifname  = caldb.rootdir() + filename
                 fits     = gammalib.GFits(cifname)
-                cif      = fits["CIF"]
-                caltable = cif["CAL_CBD"]
+                cif      = fits['CIF']
+                caltable = cif['CAL_CBD']
  
                 # Extract response names
                 names = self._get_response_names(caltable)
@@ -207,8 +196,18 @@ class cscaldb(ctools.cscript):
                 # Print response name
                 if self._logTerse():
                     for name in names:
-                        self._log(name+"\n")
-                    self._log("\n")
+                        self._log(name+'\n')
+                    self._log('\n')
+
+        # Return
+        return
+
+    def execute(self):
+        """
+        Execute the script.
+        """
+        # Run the script
+        self.run()
  
         # Return
         return
@@ -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.
+
+
+Dependencies
+^^^^^^^^^^^^
+
+- All ctools code must only depend on the ISO standard C++98 libraries and the
+  GammaLib library.
+
+
+Code lay-out
+^^^^^^^^^^^^
+
+- Each function or method starts with a curly bracket in the line following
+  the function or method name. The return type is in the same line as the
+  function or method name, e.g.:
+
+  .. code-block:: cpp
+
+     int function(void)
+     {
+         int i = 0;
+         ...
+         return i;
+     }
+
+- Code blocks should be encompassed in curly brackets, even if the block
+  consists only of a single line.
+
+- The opening curly bracket of a block starts in the same line as the
+  related statement, e.g.:
+
+  .. code-block:: cpp
+
+      for (int i = 0; i < 10; ++i) {
+          sum += i;
+      }
+
+- Separate code elements by spaces, e.g.:
+
+  .. code-block:: cpp
+
+     Yes: int i = 0;
+
+     No:  int i=0;
+
+- Align successive class definition on the member function name, e.g.:
+
+  .. code-block:: cpp
+
+     void        log10GeV(const double& eng);
+     void        log10TeV(const double& eng);
+     std::string print(void) const;
+
+
+.. To be written:
+
+   String quotes
+   ^^^^^^^^^^^^^
+
+   Whitespace in Expressions and Statements
+   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+   Comments
+   ^^^^^^^^
+
+
+Naming Conventions
+^^^^^^^^^^^^^^^^^^
+
+- Prefix data members with ``m_``, e.g.:
+
+  .. code-block:: cpp
+
+     m_num
+     m_response
+     m_grid_length
+     m_axis_dir_qual
+
+
+Programming Recommendations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- Each class shall have the protected methods ``init_members``,
+  ``copy_members``, and ``free_members`` to handle initialisation,
+  copying, and eventually freeing of allocated memory for data members:
+
+  .. code-block:: cpp
+
+     // Initialise data members
+     void Class::init_members(void)
+     {
+         m_elements = 10;
+         m_array    = new double[m_elements];
+         for (int i = 0; i < m_elements; ++i) {
+             m_array[i] = 0.0;
+         }
+         ...
+     }
+
+     // Copy data members
+     void Class::copy_members(const &Class class)
+     {
+         m_elements = class.m_elements;
+         m_array    = new double[m_elements];
+         for (int i = 0; i < m_elements; ++i) {
+             m_array[i] = class.m_array[i];
+         }
+         ...
+     }
+
+     // Free data members
+     void Class::free_members(void)
+     {
+         if (m_array != NULL) delete [] m_array;
+         ...
+     }
+
+- Each class shall have at least a void constructor, a copy constructor,
+  a destructor and an assignment operator. Additional constructors and
+  operators can be implemented as required. The following example shows
+  the basic implementation for these 4 methods. Due to the usage of the
+  ``init_members``, ``copy_members``, and ``free_members``, most classes
+  will have exactly this kind of syntax:
+
+  .. code-block:: cpp
+
+     // Void constructor
+     ctnice::ctnice(void)
+     {
+         init_members();
+         return;
+     }
+
+     // Copy constructor
+     ctnice::ctnice(const ctnice& nice)
+     {
+         init_members();
+         copy_members(nice);
+         return;
+     }
+
+     // Destructor
+     ctnice::~ctnice(void)
+     {
+         free_members();
+         return;
+     }
+
+     // Assignment operator
+     ctnice& ctnice::operator=(const ctnice& nice)
+     {
+         if (this != &nice) {
+             free_members();
+             init_members();
+             copy_members(nice);
+         }
+         return *this;
+     }
+
+- Do not use macros.
+
+- Do not use ``#define`` directives for the declaration of constants. Use
+  ``const`` instead.
+
+- Do not use ``std::strncpy``, ``std::memcpy`` or similar as these functions
+  are corrupted on some systems.
+
+- If possible, pass arguments by reference.
+
+- Output arguments should be passed as pointers.
+
+- Use C++ (``std::string``) instead of C-style (``char*``) strings.
+
+- Use C++ casts instead of C-style casts.
+
+- Avoid using templates.
+
+- Do not use an integer for a floating point argument (i.e. write 10.0
+  instead of 10). Some older compilers give an error when using
+  integers in some floating point functions, such as log10().
+
+- Where possible (and appropriate), use ``std::vector`` containers instead
+  of allocating memory. In other words: avoid direct memory allocation with
+  ``new``.
+
+- Use the ``std::`` namespace prefix where possible; write for example
+
+  .. code-block:: cpp
+
+     std::sin(angle);
+     std::cos(angle);
+
+  You may not believe it, but droping the ``std::`` may on some systems
+  lead to considerably slower code for trigonometric functions!
+
+- Use ``explicit`` for constructors with single arguments to prevent
+  unintended type conversions. The only exception to this rule is the
+  copy constructor or type conversion constructors.
+
+- Specify ``void`` for function or method definitions without arguments,
+  e.g.:
+
+  .. code-block:: cpp
+
+     Yes: void function(void)
+
+     No:  void function()
+
+- Use pre-incrementation in loops (pre-incrementation is faster than
+  post-incrementation), e.g.:
+
+  .. code-block:: cpp
+
+     for (int i = 0; i < 10; ++i) {
+         sum += i;
+     }
+General rules
+=============
+
+The general rules apply to Python and C++ code.
+
+
+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 of the function or method.
+
+- Always use English words (class names, method and function names,
+  comments, documentation, etc.).
+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 8 <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.
+
+
+Dependencies
+^^^^^^^^^^^^
+
+- All ctools code must be compatible with Python 2.3 or higher, and
+  Python 3.0 and higher.
+
+- ctools should be importable with no dependencies other than the
+  `Python Standard Library <https://docs.python.org/release/2.3/lib/lib.html>`_.
+
+
+Code lay-out
+^^^^^^^^^^^^
+
+- Put imports on separate lines, e.g.:
+
+  .. code-block:: python
+
+     Yes: import os
+          import sys
+
+     No:  import sys, os
+
+- Put imports at the top of the file, just after any module comments
+  and docstrings, and before module globals and constants.
+
+- Use absolute imports, e.g.:
+
+  .. code-block:: python
+
+     import mypkg.sibling
+     from mypkg import sibling
+     from mypkg.sibling import example
+
+
+String quotes
+^^^^^^^^^^^^^
+
+- Use single quotes for strings so that the string can contain double
+  quote characters which avoid backslashes, e.g.:
+
+  .. code-block:: python
+ 
+     Yes: print('The Parameter "infile" is missing')
+
+     No:  print("The Parameter \"infile\" is missing")
+
+
+Whitespace in Expressions and Statements
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- Do not put extraneous whitespace immediately inside parentheses,
+  brackets or braces, e.g.:
+
+  .. code-block:: python
+ 
+     Yes: spam(ham[1], {eggs: 2})
+
+     No:  spam( ham[ 1 ], { eggs: 2 } )
+
+- Do not put extraneous whitespace immediately before a comma, semicolon,
+  or colon, e.g.:
+
+  .. code-block:: python
+ 
+     Yes: if x == 4: print x, y; x, y = y, x
+
+     No:  if x == 4 : print x , y ; x , y = y , x
+
+- Do not put extraneous whitespace immediately before the open parenthesis
+  that starts the argument list of a function call, e.g.:
+
+  .. code-block:: python
+ 
+     Yes: spam(1)
+
+     No:  spam (1)
+
+- Do not put extraneous whitespace immediately before the open parenthesis
+  that starts an indexing or slicing, e.g.:
+
+  .. code-block:: python
+ 
+     Yes: dct['key'] = lst[index]
+
+     No:  dct ['key'] = lst [index]
+
+
+Comments
+^^^^^^^^
+
+- Always make a priority of keeping the comments up-to-date when the code
+  changes! Comments that contradict the code are worse than no comments. 
+
+- Comments should be complete sentences. If a comment is a phrase or
+  sentence, its first word should be capitalized, unless it is an identifier
+  that begins with a lower case letter (never alter the case of identifiers!).
+
+- If a comment is short, the period at the end can be omitted. Block
+  comments generally consist of one or more paragraphs built out of complete
+  sentences, and each sentence should end in a period.
+
+- Follow `Strunk & White <https://en.wikipedia.org/wiki/The_Elements_of_Style>`_.
+  Make every word tell. Omit needless words. Use active voice. Use parallel
+  construction on parallel concepts.
+
+- Block comments generally apply to some (or all) code that follows them,
+  and are indented to the same level as that code. Each line of a block
+  comment starts with a # and a single space (unless it is indented text
+  inside the comment). Paragraphs inside a block comment are separated by
+  a line containing a single #, e.g.:
+
+  .. code-block:: python
+ 
+     # Compute the energy boundaries.
+     #
+     # The energy boundaries are computed from the lower and upper energy
+     # thresholds that are stored in the effective area components of the
+     # response functions.
+     ebounds = gammalib.GEbounds()
+     ...
+
+- Use inline comments sparingly. Use meaningful variable names instead.
+  But sometimes, inline comments can be useful, e.g.:
+
+  .. code-block:: python
+
+     x = x + 1  # Compensate for border
+
+
+User Documentation
+^^^^^^^^^^^^^^^^^^
+
+- Write documentation strings (a.k.a. docstrings) for all modules, functions,
+  classes, and public methods.
+  Read `PEP 257 <http://www.python.org/dev/peps/pep-0257/>`_ to learn
+  about the general Python conventions for writing good documentation
+  strings.
+
+- The docstring conventions follow the common standards developed by
+  `NumPy <http://www.numpy.org>`_ and `SciPy <http://www.scipy.org>`_
+  and that are also adopted by
+  `AstroPy <http://docs.astropy.org/en/stable/development/docrules.html>`_.
+  This docstring standard uses
+  `re-structured text (reST) <http://docutils.sourceforge.net/rst.html>`_
+  syntax and is rendered using
+  `Sphinx <http://www.sphinx-doc.org/en/stable/>`_.
+  While a rich set of markup is available, limit yourself to a very basic
+  subset, in order to provide docstrings that are easy to read on text-only
+  terminals.
+
+- Format each docstring as follows (sections can be omitted if they do
+  not apply, for example you do not need to specify that nothing is 
+  returned):
+
+  .. code-block:: python
+
+     """
+     Extract calibrations for a mission from a calibration database.
+
+     .. note:: Deprecated in ctools 1.1
+               The `instrument` string will be removed in ctools 2.0 because
+               it's in fact not used by the method.
+
+     The method extract calibration names from a calibration database by
+     scanning all index files.
+
+     Parameters
+     ----------
+     caldb :  `~gammalib.GCaldb`
+         Calibration database.
+     instrument : str
+         Instrument names.
+     debug : bool, optional
+         Turn on debugging if needed.
+
+     Returns
+     -------
+     missions : list of str
+         List of mission names.
+
+     Raises
+     ------
+     ValueError
+         If `instrument` is not recognised as among the ones implemented.
+
+     See Also
+     --------
+     irfs : Return all irfs for a given calibration.
+
+     Notes
+     -----
+     See https//my.site.edu for documentation. The method computes
+
+     .. math:: X(e^{j\omega } ) = x(n)e^{ - j\omega n}
+
+     where the value of :math:`\omega` is larger than 5.
+
+     References
+     ----------
+     .. [1] J. Public, "The art of programming", Computers & Geosciences,
+        vol. 22, pp. 585-588, 1996.
+
+     Examples
+     --------
+     >>> calibrations(caldb, "CTA", debug=False)
+     ['Prod2', 'Prod3']
+     """
+
+- For the parameter types, be as precise as possible. Below are a few examples
+  of parameters and their types.
+
+  .. code-block:: python
+
+     Parameters
+     ----------
+     filename : str
+     copy : bool
+     dtype : data-type
+     iterable : iterable object
+     shape : int or tuple of int
+     files : list of str
+
+- For classes, use the same sections as outlined above. The constructor
+  (``__init__``) should also be documented here, the Parameters section of
+  the docstring details the constructors parameters. An Attributes section,
+  located below the Parameters section, may be used to describe class
+  variables:
+
+  .. code-block:: python
+
+     Attributes
+     ----------
+     x : float
+         The X coordinate.
+     y : float
+         The Y coordinate.
+
+- In general, it is not necessary to list class methods. In some cases,
+  however, a class may have many methods, and then it becomes useful to have
+  an additional ``Methods`` section:
+
+  .. code-block:: python
+
+    Methods
+    -------
+    read(filename)
+        Read a table from a file
+    sort(column, order='ascending')
+        Sort by `column`
+
+
+Naming Conventions
+^^^^^^^^^^^^^^^^^^
+
+- Use short lowercase abbreviate words for cscripts, e.g.:
+
+  .. code-block:: python
+
+     cspull
+     csspec
+     cslightcrv
+
+- Use ``lower_case_with_underscores`` for functions, methods, and variables.
+
+- Use ``self`` for the first argument to instance methods, e.g.:
+
+  .. code-block:: python
+
+     def __init__(self, name):
+	     self._name = name
+
+- Use one leading underscore for private methods and instance variables,
+  e.g.:
+
+  .. code-block:: python
+
+     self._get_energy_boundaries()
+     self._has_ebounds = True
+
+- Always decide whether a class's methods and instance variables
+  (collectively: "attributes") should be public or private. If in doubt,
+  choose private; it's easier to make it public later than to make
+  a public attribute private.
+
+
+.. To be written:
+
+   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