hypre/docs_misc/dev_coding.tex

%==========================================================================
\chapter{Coding Standards}
\label{Coding Standards}

These guidelines are based on those provided by the ISE project in
CASC.  See
\htmladdnormallink{file:/home/casc/software\_development/html/index.html}{file:/home/casc/software\_development/html/index.html}
for more info.

%==========================================================================
\section{General Guidelines}
\label{General Guidelines}

The guidelines given in the ISE project document \file{coding_style.ps}
should be followed.  There are a few additions/changes that should
be made here:
\begin{enumerate}

\item The "order of parameters" section should be modified so that
opaque object names always appear first in the argument list.  For
example, a routine for setting the coefficients of a matrix object
should look like
\begin{verbatim}
   HYPRE_SetMatrixCoeffs(matrix_object, ...)
\end{verbatim}
even though the \code{matrix_object} is an I/O parameter.  This is just to
provide some consistency.

\item Guidelines for indentation are given below.

\item Guidelines for documentation are given below.

\item No function will return void.  Integer return values will be used
to indicate error status.  This will primarily affect "New" functions.

\end{enumerate}

%==========================================================================
\section{Naming Conventions}
\label{Naming Conventions}

\begin{enumerate}

\item Functions and macros with parameters should be named as follows:

\begin{verbatim}
   HYPRE_MixedCase(...)          /* User interface routines *
   hypre_MixedCase(...)          /* Internal non-user routines *
\end{verbatim}

\item Macros without parameters should be named as follows:

\begin{verbatim}
   HYPRE_ALL_CAPS          /* User interface macros *
   hypre_ALL_CAPS          /* Internal non-user macros *
\end{verbatim}

\item Types should be named as follows:

\begin{verbatim}
   HYPRE_MixedCase          /* User interface types *
   hypre_MixedCase          /* Internal non-user types *
\end{verbatim}

\item It is preferred that variables be named as follows:

\begin{verbatim}
   lower_case_with_underscores
\end{verbatim}

This is not a strict rule, but in general one should try to adhere to
this so that it is easy to distinguish variables from functions and
macros.

\end{enumerate}
 
%==========================================================================
\section{User interface vs. internal code}
\label{User interface vs. internal code}

The term "user" here refers to someone who wants to solve linear systems,
but is not developing linear solvers.  The term "internal code" refers to
code that is not part of the user interface.

NOTE: It is important to clearly distinguish between supported
routines and everything else in the library.  The mechanism described
below is one way of making this explicit.

The following convention has been used to some degree already in
\hypre{} for separating the two above notions.  Files containing
internal routines are given names WITHOUT the \code{hypre_} prefix and
include only ONE internal header file with some name that is unique in
the \hypre{} library (Note: The SMG code currently uses the convention
of giving this header file the same name as the subdirectory it lives
in.  See the below example).  All user interface routines are defined
in files beginning with the prefix \code{HYPRE_}.  One user interface
header file is defined that contains prototypes, etc., for the
interface routines.

By doing this, it is easy to create prototypes for internal routines and
user interface routines.  For example,
\begin{verbatim}
  mkproto *.c >> this_directory.h
  mkproto HYPRE_*.c >> HYPRE_lib.h
\end{verbatim}

We should continue this convention for now.  It is possible that this
may be changed to some other convention in the future, but if we have
a common way of doing it now, it will be easier to change later.

%==========================================================================
\section{Indentation}
\label{Indentation}

The ISE project file \file{sample.emacs} should be used to provide a common
indentation style for the library.  If you don't use emacs as your
editor, you can use the scripts written by Rob Falgout to indent files
from the shell command line.  See the README file in \file{~falgout/tools}.

The files \file{sample_c_code.c} and \file{sample_f77_code.c} have
been provided as examples of indentation style for \hypre{}.  They are
modifications of those provided by the ISE project.

NOTE: the Fortran source file and the Fortran mode defined in
the \file{sample.emacs} file do not agree.  The Fortran part of this
document needs work.  Volunteers?