128 lines
4.6 KiB
TeX
128 lines
4.6 KiB
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?
|
|
|