SAS Coding Standards

Contents

• Fortran-90 coding
• Fortran-90 headers
• C++ coding
• C++ headers
• Scripts

Fortran-90 Coding

Structure

Module names shall be lower case. The name of a file containing a module, shall be the module name with the suffix `.f90'.

Any algorithm that is likely to be needed in more than one subprogram should not be implemented in a subprogram but instead be put into a library or access layer. This includes error handling (also when opening files), parameter access, data file access and the like, but also any generic subroutine such as FFT, sorting, selecting, general vector and matrix math etc.

The include statement shall not be used; use modules instead.

Readability

Procedure argements should be given with the intent(in) items first, then those with intent(inout). A possible exception is a status flag as the last argument.

The code shall be written in lowercase.

Fortran keywords (such as data) shall not be used as variable names.

The names of intrinsic functions (such as sum) shall not be used for user-defined functions.

Statement lines shall be indented in order to make the program structure clear. For example, if, do and case blocks should be indented.

The Fortran-90 relational operator symbols (e.g. `$>$') shall be used in preference to the older .gt. style.

The end statements of long blocks such as if, do, case and main program and subroutine sections, shall use the label matching the original start of the block to make the structure more obvious.

Variable names shall use the Fortran-90 facility for longer variable names (i.e. short cryptic names should be avoided).

Comment lines shall be separated from the main code by a single line. A space should be left between the `!' marker and the text.

All code shall be in lower case, but variable and function names can use uppercase letters to delimit words in the name (e.g. focalLength). User-defined types shall start with an upper-case letter.

Continuation lines shall be indented with respect to the first line.

Initial values for variables should, where they are needed, be given in the type statement.

Variables should not be reused for a different purpose, but a new one declared for each new purpose.

The implicit none construct shall be used and all variables shall be explicitly declared.

Procedures that return a single value should be functions. Note that single values could also be user-defined types.

Trailing optional arguments shall be specified with dummy arguments (call foo(bar=1) instead of call foo(1)).

Robustness

Character dummy arguments should have a length specified as (len=*) where possible.

Generic subroutines/functions should be written using assumed shape arguments where appropriate.

Identifiers in a module should be made private by default. They shall be declared public if they are part of the public interface of the module.

A case statement shall always have a default clause.

Subroutine and function arguments shall use the intent descriptor.

Obsolete or to be avoided

High Performance Fortran extensions shall not be used.

Common blocks must not be used. Modules should be used instead, where shared access to data is necessary.

Equivalence statements shall not be used.

Entry statements shall not be used.

Goto statements should not be used. One exception would be a single global label for error conditions. Note: For jumping out of nested loop constructs, the Fortran-90 exit statement should be used.

The P-format descriptor should not be used. Use the ESw.d or ENw.d instead.

Do not use units without opening. It is not safe to assume that certain units are connected to standard input, standard output or standard error. Use unit=* for standard input and output.

Comment lines shall be separated from the main code by a single line. A space should be left between the `!' marker and the text.

Before opening a file a unit number has to be retrieved from the library function getUnit.

Do not use namelist I/O.

The save statement is discouraged. Better use module variables for state.

The following obsolete features shall not be used:

• arithmetic if
• assign statement
• assigned goto
• assigned format
• block data
• equivalence
• sequence
• Hollerith strings
• pause statement
• real & double-precision do-loop index variables and control expressions
• shared do-loop termination
• branching to endif from outside the if block
• non-generic type conversions such as ifix, float and sngl.

• the %val notation in procedure arguments
• declarations of the form {\em byte}, {\em integer*2}, {\em real*8} etc. etc. Use the {\em kind} selection instead.
• format descriptor $
• Format descriptor Q
• open(readonly). Use open(action="read")
• open(access="append"). Use open(position="append")
• open(carriagecontrol="list")

Fortran-90 File Headers

!+
! Module: example_mod
!
! Authors: Giuseppe Vacanti, ESA/ESTEC
!
! Description: example f90 header
! 
! Comments: just an example
! 
! $Id: coding.html,v 1.5 2001/09/21 10:20:31 gvacanti Exp $
!- 
module example_mod

  use dal
  use param  
  
  implicit none 
  
  private 

  public example

contains 
  
  !---------------------------------------------------------------------
  subroutine example
  !---------------------------------------------------------------------
    

  end subroutine example
  
end module example_mod





This header
is automatically created by running pkgmaker.

C++ Coding

A source file shall normally define only one class. However, it may be appropriate to include a small related class, such as an iterator for a container class.

The file name of a class shall be the same as the class name, with the suffices `.cc' and `.h'. Source files which do not contain classes (e.g. main.cc), shall have names starting with a lower-case letter.

Header files shall define a symbol, to prevent multiple inclusion, which is the name of the file capitalised, with `.h' replaced by `_H'. For example, FooBar.h should contain:

Global symbols, other than class names, shall be avoided where possible. Constants, types, etc should be defined within the scope of a class. For example:

static const float c = 2.99792458E8; // Speed of light (m/s)
enum Color {Red, Green, Blue};
typedef list<Source> SourceList;

• namespaces
• exceptions
• run-time type identification (RTTI)

For example, J.Brumfitt has registered the prefix Qjb, resulting in class names such as QjbDoubleEdit.

Other classes should have names which are unlikely to clash with Qt, STL, GNU and other standard libraries. However, general purpose classes should not use the application name (i.e. Sas) as the prefix.

Classes which dynamically allocate memory, such that the default shallow copy does not work, must either implement a copy constructor and assignment operator, or disable these functions (by declaring them private).

Member functions, function argument and function return types shall be declared `const' where possible. (This may not always be possible where existing non-const functions are used.)

• Member functions should be declared `const' if they do not modify the state of the object.
• Reference and pointer type arguments should be declared `const' if the function does not modify the argument.
• Functions returning reference types should have the return types declared `const' if possible.

Assignment operators should always test for self-assignment (e.g. x = x).

Member data should be declared private (or protected where appropriate).

The use of `friend' declarations should be avoided, except for overloaded global operators defined in the same files as the class (e.g. operator<<).

Pointers should be set to 0 after a `delete' operation if they remain in scope.

All classes should define an operator<<, as this is useful for debugging. Where there is too much data to print, the operator may simply print the class name or a short summary of the object's state.

Member functions which directly access member variables should normally have the same name as the variable, but without the underscore. For example, _foo would be accessed by a function foo().

A class with any method declared virtual must have its destructor declared virtual. If it has no destructor, then an empty destructor must be added, since the default destructor is non-virtual.

Header files should be compatible with the cxx2html source code documentation tool. This automatically extracts source code documentation, provided that the comments are in a suitable format.

Each member function shall be described by a short comment preceding it in the header file.

C++ Header Files

// Constructors
Source();
Source(double ra, double dec);
// Return the right ascension in degrees
double ra() const { return _ra; }
// Return the declination in degrees
double dec() const { return _dec; }
// Write to a stream
friend ostream& operator<<(ostream&, const Source&);

double _ra;
double _dec;

Scripts

If you are writing a shell script or PERL script, for inclusion in
the SAS, please keep to the following rules to ensure portability:

Use only "sh", "csh" or "perl". Other shells, such as "tcsh" and "bash" may not be available on other people's machines.

Do your development and testing under Solaris, so you get a real Bourne shell or C-shell. The Linux versions are simply symbolic links to "bash" and "tcsh".

The #! line should specify one of the following paths:

#!/bin/sh
#!/bin/csh
#!/usr/local/bin/perl
(The distribution of Perl installs itself by default in /usr/local/bin/perl. If it is elsewhere, make a symbolic link in /usr/local/bin.)

Don't use "awk" scripts. Use "perl" instead.

Use portable command-line options for unix utilities. For example:
ln -sf                          works on linux but not Solaris
ln -f -s                        is more portable

Scripts should run on an ordinary Solaris installation (+ any programs explicitly mentioned in the installation instructions). For testing, it is a good idea to put the Solaris utilities in front of the GNU utilities in your path. Also, put /usr/bin and /usr/ccs/bin  before /usr/ucb/bin in your path (for Solaris) so you get the System V versions of utilities.