% /*@@
%   @file      Style.tex
%   @date      Wed Jan 12 15:01:09 2000
%   @author    Tom Goodale
%   @desc 
%   
%   @enddesc 
%   @version $Header$
% @@*/
\begin{cactuspart}{1}{Philosphy and Style}{$RCSfile$}{$Revision$}
\renewcommand{\thepage}{\Alph{part}\arabic{page}}

\chapter{Philosophy} 

\begin{itemize}
\item
Portable
\item
Extensable
\item
Modular
\end{itemize}

\chapter{Coding Style}

The flesh has been written with the following coding guidelines...


\section{Indentation}

Two spaces, no tabs.

Two spaces are enough to clearly indent, more would be a waste of
space, less not really noticeable.

\section{Brace positioning}

Each opening brace should appear on a line by itself,
aligned with the preceeding statement.

Closing braces should line up with the corresponding
opening brace, and should be on lines by themselves
apart from the {\tt while} in a 
%
\begin{verbatim}
do
{

...

} while(...);

\end{verbatim}
%
statement.

This brace positioning stategy makes it easy to run ones eye from a closing
or opening brace to its matching opening or closing brace.

\section{GRDOC}

All files should start with a grdoc header, and all functions
should have grdoc headers.

The file grdoc should contain a description of the contents of the file
and an \@version with the CVS \$Header\$ tag.

The function grdoc should contain

\begin{itemize}
\item
a description of the function, saying what it does.
\item
all function arguments with descriptions
of what they are and what they are used for.
\item
the return codes should be described.
\end{itemize}

After the first actual release the history should be filled
in with each change.

\section{Header Files}

Header files should not include any system header file, but should
contain in the initial comment a list of system header files which
are assumed to have been included before this file is included.

The body of a header should be protected against multiple inclusion
by lines of the form

\begin{verbatim}
#ifndef _NAMEOFHEADERFILEINCAPITALS_H_
#define _NAMEOFHEADERFILEINCAPITALS_H_

...body of header file...

#endif /* _NAMEOFHEADERFILEINCAPITALS_H_ */

\end{verbatim}

Function prototypes in header files should be protected
against C++ linkage by

\begin{verbatim}
#ifdef __cplusplus
extern "C" 
{
#endif

...prototypes...

#ifdef __cplusplus
}
#endif
\end{verbatim}

\section{Source Files}

Source files should have as their first line under the 
grdoc header a line containing

\begin{verbatim}
static char *rcsid = "$Header$"
\end{verbatim}
or the expanded rcs version of this.

Globally visable functions should appear before local
functions.

(NOTE: currently the schedule stuff is a good example of
what I'm coming to like as a style, e.g.
src/main/ScheduleInterface.c )

\section{Naming Conventions}

All functions which may be used by thorns should have names beginning
with {\tt CCTK\_}.

All functions used internally by the flesh should have names beginning with
{\tt CCTKi\_}.

Header files to be included by thorns should have names beginning with
{\tt cctk\_}.




%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\end{cactuspart}
