.. +
..
..
.. TODO
.. ====
..
.. justification
..
.. tools
..
.. add reference to pylint and PEP
..
.. emphase good and bad examples
..
.. ne pas utiliser de mot clé : ex test en shell, image en matlab 
..
.. EVOLUTIONS
.. ==========
..
.. $URL$
..
.. - fplod 20110308T100953Z aedon.locean-ipsl.upmc.fr (Darwin)
..
..   * small improvements. add ref to runtestdemo.
..
.. - fplod 20110303T160756Z aedon.locean-ipsl.upmc.fr (Darwin)
..
..   * add octave/matlab section
..
.. - fplod 20101125T075803Z aedon.locean-ipsl.upmc.fr (Darwin)
.. 
..   * creation
..
.. _

.. _coding_rules:

Coding rules
============

.. _files_extension:

Files extension
---------------

Shell scripts : :file:`.sh`

IDL scripts : :file:`.pro`

Octave/Matlab scripts : :file:`.m`


Files contents
--------------
 
No multiple statement 

bad::

 a=1;b=2

good::

 a=1
 b=2

No comment after a statement


bad::

 yyyy=2010 # default yyyy value

good::

 # default yyyy value
 yyyy=2010

Lines length
~~~~~~~~~~~~

Lines length should be shorter than 79 characters.

Exception : long URL

++ see continuation lines in ++

Comments
~~~~~~~~

Comments should describe functionalities and implementation choices.

A good way to see if there are enougth comments is to read files without instructions (:samp:`sed -e "/^#/d" file.sh`) : do you understand ?

+todo+ see also headers

Tabs, blanks
~~~~~~~~~~~~

No trailing blank
 justification : for example, when a trailing blank is after \ (continuation lin) in a shell script, it won't work anymore

No trailing empty line

No tab

No multiple blanks except leading ones.

Indentation at least 3 in block IF, WHILE, etc.

Indentation at least 3 when multiple lines statement

Shell scripts
~~~~~~~~~~~~~

First line ::

#! /bin/sh


IDL scripts
~~~~~~~~~~~

Unabbreviated keywords
......................

justification : avoiding confusion, either to find help

Continuation lines
..................

bad example::
  
    +todo+ first part , $
    +toto+ second part

good example::

    +todo+ first part $
    , second part 

Explicit IF ... ENDIF block
...........................

same for loop (while, until, etc.)
::

 IF (yyyy LT 1999) THEN PRINT, 'too soon'

::

 IF (yyyy LT 1999) THEN BEGIN
    PRINT, 'too soon'
 ENDIF

Interaction with system
.......................

No :command:`spawn`

 justification : error handling, portability (unix, windows)

Test with NaN
.............

bad ::

 myvar EQ !VALUES.F_NAN

good

 finite(myvar) EQ 0

cf. dave fanning +todo link

Test with float
...............

bad ::

 myvar1 EQ myvar2

good+todo+
 
 +- espilon machin


Octave/Matlab scripts
~~~~~~~~~~~~~~~~~~~~~

Footers
.......

Add demo and test

 justification : robustness

 see :ref:`rundemotest`

Functions
.........

Use function calling form rather than procedure

 justification : error handling

bad ::

  load ginette
    
good ::

  data=load('ginette')

Interaction with system
.......................

No :command:`!`

 justification : error handling, portability (unix, windows)

bad::
  
  !echo $ARCH

good::

  my_ev=getenv('ARCH')

Test with float
...............

bad ::

 myvar1 == myvar2

good+todo+::
 
 matlab +- espilon machin
 octave assert(myvar1,myvar2)

IF block
........

always an :command:`else` if :command:`elseif`

switch block
............

always an :command:`otherwise`