1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
|
% /*@@
% @file Style.tex
% @date Wed Jan 12 15:01:09 2000
% @author Tom Goodale
% @desc
%
% @enddesc
% @version $Header$
% @@*/
\begin{cactuspart}{1}{Philosphy and Style}{}{$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;
all {\tt Cactus*} thorns should also follow them.
\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.
Braces should be used for all {\tt if} and {\tt for} statements.
\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 a \@version with the CVS \$Header\$ tag.
The function grdoc should contain
\begin{itemize}
\item
a description of the function, saying what it does.
\item
the functions called by this function.
\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}
Note that the `calledby' field {\em should not} be filled in as
this is unmaintainable.
The standard grdoc function header is of the form
\begin{verbatim}
/*@@
@routine Template
@date Fri Oct 6 10:51:49 2000
@author Tom Goodale
@desc
An example of grdoc
@enddesc
@calls templatefunc2
@calledby
@history
@endhistory
@var templatestring
@vdesc string describing foobar
@vtype const char *
@vio in
@vcomment
@endvar
@returntype int *
@returndesc
0 - success
or the returncode of @seeroutine templatefunc2
@endreturndesc
@@*/
\end{verbatim}
This is the form which will be created if you use the grdoc emacs mode.
The variable descriptions and the return code decription should be placed
after the history so that they are close to the actual function.
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_ 1
...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}
The Cactus header files ({\tt cctk\_<name>}) should only include
information relevant for thorn programmers.
There is a template file in the doc/MaintGuide directory.
\section{Source Files}
Source files should have as their first lines after all the include
files:
%\begin{verbatim}
\vskip .3cm
{\bf static const char $*$ const rcsid = "\$Header\$"; }
\newline
{\bf CCTK\_FILEVERSION($<$source file$>$);}
%\end{verbatim}
\vskip .3cm
or the expanded rcs version of this. The macro {\bf CCTK\_FILEVERSION} is
simply there to prevent compiler warnings, and {\bf $<$source file$>$}
should be replaced by
\begin{itemize}
\item{} Flesh: {\bf $<$directory$>$\_$<$core filename$>$\_$<$extension$>$} (e.g. {\bf main\_Groups\_c})
\item{} Thorn: {\bf $<$arrangement$>$\_$<$thorn$>$\_$<$core filename$>$\_$<$extension$>$}\\ (e.g. {\bf CactusBase\_CartGrid3D\_CartGrid3D\_c})
\end{itemize}
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 )
There is a template file in the doc/MaintGuide directory.
\section{Naming Conventions}
All functions which may be used by thorns should have names beginning
with {\tt CCTK\_} and then capitalised words with no underscores.
All functions used internally by the flesh should have names beginning with
{\tt CCTKi\_} and then capitalised words with no underscores.
Header files to be included by thorns should have names beginning with
{\tt cctk\_}, and followed by capitalised words with no underscores.
Structures which may be used by thorns should have names beginning with
{\tt c} and then capitalised words, {\it e.g.} {\tt cGroup}. The
exception here is structures associated with utility routines which
are not Cactus specific, there the structure names should start with a
{\tt t\_}.
Structures which are purely internal to the flesh should have
names beginning with {\tt i}.
All Cactus sourcefile names (except general utility files) should
use capitilised words without underscores.
\section{Functions}
All functions should have a grdoc header.
They should have a single place of return at the end of the function to
make it easy to tidy up and work out what is going on.
Where possible variables should be declared at the top of the function with
no initialisation, and then initialised after all variable declarations. Of
course this can't apply to static variables, 'though these should be kept to
a minimum so we can make a thread-safe version of Cactus later.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\end{cactuspart}
|
