%=======================================================================
% CVS: $Id: ice_code_std.tex 5 2005-12-12 17:41:05Z mvr $
% CVS: $Source$
% CVS: $Name$
%=======================================================================

\section{Coding Standard}

The goal of a coding standard is to create source code that follows
a consistent style, giving the sea ice model a common look and better
readability.  For historical reasons, the current code does not
completely conform to all of the following standards.  Work is in 
progress to correct this. The coding standard will be enforced through
code reviews.

%============================================================================
\subsection{Style Guidelines}

\subsubsection*{General Guidelines}

\begin{itemize}

\item {\bf Fortran 90 Standard} CSIM uses the F90 standard.

\item {\bf Preprocessor} The C preprocessor is required as the macro
                         processor (cpp).  All tokens should be
                         uppercase to distinguish them from fortran code.
                         The use of ifdef constructs should be avoided
                         wherever possible.  The option should be set in
                         the namelist instead.

\item {\bf Fixed-Form Source} Fixed-form source will be used for readability.
       Columns 7 to 72 of a line may contain a Fortran statement, while columns
       1 to 6 are reserved for special purposes.  Blanks may be used freely
       anywhere.  Exclamation marks should be used to denote comments.
       A statement may include a maximum of 19 continuation lines. 

\item {\bf Bounds Checking} All code should be able to run when the following
      compiler options are set:
      \begin{itemize}
        \item Array bounds checking
        \item Automatic variables are initialized to NaN
        \item Floating point exception conditions: overflow, division by zero, and
              invalid operations 
      \end{itemize}

\end{itemize}

%---------------------------------------------------------------------------
\subsubsection*{Modules}

\begin{itemize}
  \item The use of modules is strongly encouraged since they provide global
        access to variables.
  \item Modules must have the same name as the file in which they reside,
        due to dependency rules used by "make" programs.        
        This implies that multiple modules are not allowed in a single file.
  \item Module names must begin with "ice\_".  This will provide unique
        module names when CCSM is released as a single executable version.
  \item Related subroutines and variables should be placed in
       a single module/file rather than keeping a single routine per file.
  \item The use of common blocks is discouraged.  Modules are a better
        way to provide access to declared entities via the "use" statement.
  \item If possible, access to variables should be limited through use of
        {\tt only} and {\tt private} clauses in the "use" statements.
\end{itemize}

%---------------------------------------------------------------------------
\subsubsection*{Subroutines}
\begin{itemize}
  \item {\bf \textsl{Inline}} any subroutine or function that is only called once, unless
        it contains a significant amount of physics.
  \item Minimize work arrays and other extraneous copies unless the array is
        used multiple times within the same subroutine.  Globally accessible
        work arrays are available in {\bf ice\_work.F}.
\end{itemize}
%---------------------------------------------------------------------------
\subsubsection*{Loops}

\begin{itemize}
  \item  Loops should be structured with the {\tt do}-{\tt enddo} construct as
         opposed to numbered loops.
  \item  Loops should be combined as much as possible for readability and
         performance.
  \item  Subroutine calls within loops over horizontal indices i and j should
         be avoided to produce a more vector-friendly code.
  \item  Short loops should be placed outside of longer loops to produce 
         vector-friendly code.  For example, loops over ice thickness categories
         should be placed outside of loops over horizontal indices {\it i}
         and {\it j}.
\end{itemize}

%---------------------------------------------------------------------------
\subsubsection*{Array Syntax}

\begin{itemize}
  \item Whole array expressions are encouraged for performance reasons.
        For example,
  \begin{verbatim}
                 do i = 1, imt
                   a(i) = b(i) + c(i)
                 enddo
  \end{verbatim}
  is more desirable than
  \begin{verbatim}
                 a = b + c
  \end{verbatim}
   
\end{itemize}

%---------------------------------------------------------------------------
\subsubsection*{Allocatable Arrays}
\begin{itemize}
  \item Allocatable arrays should be avoided for performance reasons.
\end{itemize}
%---------------------------------------------------------------------------

\subsubsection*{Variable Names}

\begin{itemize}
  \item {\bf State Variables} Primary state variables should use the following
         naming convention:
  \begin{itemize}
    \item {\tt aicen(i,j,n)} ice concentration for each ice category
    \item {\tt aice(i,j)} ice concentration aggregated over all ice categories
    \item {\tt ain(n)} ice concentration in a single column, for each ice category
  \end{itemize}

  Variables that are not state variables but are used in a similar manner should
  also follow this naming convention.  Note that {\tt ai} is not a good choice
  for a variable name.

  \item {\bf Descriptive Names} Variable names should be descriptive and long
        enough to be found, for example with the UNIX "grep" utility, without
        pages of extraneous material.  For example,
        {\tt eice} and {\tt esno} are preferable to {\tt ei} and {\tt es}.
 
  \item {\bf Variables with Similar Names} Variables with the same name, but
         with different numbers of arguments should not be used in different
         places.  For example, an array {\tt Ts(i,j)} in one subroutine should
         not be used as a local variable {\tt Ts} in another.  An exception
         to this would be the {\tt work} arrays, which should always be local.
\end{itemize}
%---------------------------------------------------------------------------

\subsubsection*{Variable Declarations}

\begin{itemize}
  \item  Variables should be declared in F90 format, using a double colon.
  \item  The F90 {\tt kind} type should be used for all variable declarations.
  \item  Continuation lines are encouraged for declarations of arrays that
         have similar kinds and dimensions.  For example:
  \begin{verbatim}
      real (kind=dbl_kind), dimension (imt_local,jmt_local) ::
     &   aice     ! concentration of ice
     &,  vice     ! volume per unit area of ice          (m)
     &,  vsno     ! volume per unit area of snow         (m)
  \end{verbatim}
  \item Variables should be declared one per line to allow a comment field
        after it, with a "!" character followed by the comment text.
  \item Variables of a similar type and function may be grouped together on
        a single line.  For example:
  \begin{verbatim}
     integer (kind=int_kind) :: nyrp,mdayp,weekp       ! previous year, day, week
  \end{verbatim}
\end{itemize}
%---------------------------------------------------------------------------

\subsubsection*{Code indentation}

\begin{itemize}
  \item Code within loops and if blocks will be indented three characters.
  \item Continuation lines of an assignment statement should begin to the
        right of the assignment operator.  For example, 
  \begin{verbatim}
   Fresh(i,j) = Fresh(i,j) + (vsn(nc)*Rside*rhos
  $                        +  vin(nc)*Rside*rhoi)/dt
  \end{verbatim}
  \item Continuation lines of a subroutine call should begin to the
        right of the "(" character.  For example, 
  \begin{verbatim}
   call comp_matrices  ( rowflg, hin, Hmean,
  $                      Gamm, HGamm, H2Gamm )
  \end{verbatim}
\end{itemize}
%---------------------------------------------------------------------------
\subsubsection*{Commenting of code}

\begin{itemize}
  \item  Comments enclosed in horizontal lines are "major":
  \begin{verbatim}
  !-----------------------------------------------------------------
  ! initializations
  !-----------------------------------------------------------------
  \end{verbatim}
  while those indented to match the following pertinent code are "minor":
  \begin{verbatim}
  ! compute aggregate ice state and open water area
  call aggregate
  \end{verbatim}

  \item Short comments can be included on the same line as the source code
        preceded by the "!" character.
  \item Comments on adjacent lines should be aligned, if possible.
\end{itemize}

%----------------------------------------------------------------------
\subsubsection*{Portability}
\begin{itemize}
  \item  The code will run on all platforms supported by CCSM.  See the CCSM
         User's Guide for the most recent list of supported machines and platforms.
  \item  Code should be developed using standard MPI (Message Passing Interface).
  \item  The code should run efficiently on cache-based and vector machines.
  \item  Standard F90 and MPI should be used so that the code is easily
         portable to other platforms.
\end{itemize}

%----------------------------------------------------------------------
\subsubsection*{Incomplete and dead code}
\begin{itemize}
  \item Incomplete code should be indicated by comments that include "TBD".
  \item Variables that are declared but not used should be removed.
  \item Code that is commented out should either be removed or contain
        comments as to why it is still there.
\end{itemize}

%----------------------------------------------------------------------

\subsubsection*{Miscellaneous}
\begin{itemize}
\item Tabs should not be used for spacing; they create a large inconvenience
      when editing.
\item Code will be written in lower case.  This differentiates Fortran code
      from C preprocessor tokens, since the convention has been established
      that these are upper case.
\item Use of the relational operators $<$, $>$, $<$=, $>$=, ==, and /= are preferred
      to {\tt .lt., .gt., .le., .eq.,} and {\tt .ne.} for purposes of readability.
\item The {\tt stop} command should be avoided when exiting the code after an
      error. Instead, the subroutine {\it abort\_ice} should be called.
\end{itemize}

%=====================================================================
\subsection{Content Guidelines}
%=====================================================================


\begin{itemize}
  \item {\bf Sign Conventions}  Enthalpy is defined as negative; fluxes
        are positive downward.

  \item {\bf Implicit None}  All modules will include an {\tt implicit none}
        statement, immediately following the {\tt use} statements.  This
        implies that all variables must be explicitly typed.

  \item {\bf Prologues}  Each module, subroutine and function will include
        a prologue for use with the ProTeX auto-documentation script
        (http://dao.gsfc.nasa.gov/software/protex).  This will be used
        to make a code reference document.
 
  \item {\bf I/O Error Conditions} I/O statements which need to check an
        error condition, i.e. namelist read statements, should use the 
        {\tt iostat = <integer variable>} construct instead of {\tt end} and
        {\tt err}.

  \item {\bf Intent} All dummy arguments should include the {\tt INTENT}
        clause in their declaration.

  \item {\bf Conditionals} Conditionals based on $<$ 0. or $>$ 0. should be avoided.

  \item {\bf Physical Constants} Values of physical constants should not be 
        hardwired into the executable portion of a code.  Constants should be
        defined in a single module as named, full-precision parameters.  
        
  \item All units should be in MKS; CGS conversions should be avoided.  
        Diagnostics and other fields that do not affect the model integration
        may be in other units.
\end{itemize}

%----------------------------------------------------------------------
