3
This file is only intended for contributors of code to Pythia 8.
4
As a normal user you need not read it.
6
A reasonably consistent coding style enhances readability and
7
understanding of code, so do take the time to make new code
8
blend smoothly with the existing structure. That said, complete
9
consistency is impossible, and style must always come second to
10
content. So any rules should be applied with common sense.
12
Remember to update the xmldoc documentation in parallel with the
13
code updates. The xml rules are provided after the coding rules.
15
-----------------------------------------------------------------------
17
For the Pythia8 code some principles have been used, some by
18
deliberate decision, while others evolved organically.
19
An incomplete list is as follows.
21
1. Use existing files to get a feel for the general outlay.
22
(Especially the "core" files that have set the standard for
23
later writing, e.g. Pythia, Event, or Basics.)
25
2. Use standard C++, in a clear and consistent manner. Do not
26
show off by using special tricks that only experts will
27
appreciate. Do not use any experimental language features.
29
3. English is the only allowed language (for comments, variable
32
4. Lines should be at most 79 characters long, so that they do
33
not overflow when opened in an 80 characters wide text editor
34
window. This number includes any trailing blanks, another
35
"feature" that should be avoided.
37
5. Never make code dependent on the presence of external libraries.
38
Some libraries, like LHAPDF and HepMC are already interfaced,
39
but only in well-defined non-critical manners. If you want to
40
include interfaces to new libraries, or modify the existing ones,
41
you should bring it up for open discussion beforehand.
43
6. The underscore "character" should be avoided as far as possible;
44
it makes code difficult to read. See also point 24. Currently it
45
is only used in headers, for #ifndef Pythia8_filename_H.
47
7. Extra code used for debugging purposes, or left behind from
48
the development process, even if commented out, should be
49
removed from the public version. Feel free to save your own
50
private versions where such code is available.
52
8. Begin each code file with
53
// (filename) is a part of the PYTHIA event generator.
54
// Copyright (C) 2012 Torbjorn Sjostrand.
55
// PYTHIA is licenced under the GNU GPL version 2, see COPYING for details.
56
// Please respect the MCnet Guidelines, see GUIDELINES for details.
57
to establish the legal structure. Follow that with specific
58
information on authorship of the particular file, where relevant,
59
and a very brief summary of the contents. After that follow with
60
#include and other preprocessor commands and namespace Pythia8 {,
61
before the actual code.
64
//==========================================================================
65
to separate classes from each other, and from top and bottom
66
material of a file, that does not belong to a class.
69
//--------------------------------------------------------------------------
70
for smaller subdivisions than above. Specifically, in .cc files,
71
insert it between the different methods that belong to the same
74
11. Blank lines should be used to separate the code into suitable
75
chunks of statements that belong together. Never use two or
76
more blank lines consecutively, however.
78
12. Begin each code chunk with one or more comment lines that
79
explains the purpose of this chunk. Do not overdo documentation,
80
however: the purpose is to provide overview, not clutter.
82
13. Comment lines may also precede a particularly crucial statement
83
inside a code chunk, without the need for a blank line before.
85
14. Do not add comments on the same line as a statement:
86
a = b + c; // No comment here!
88
15. Write comments in terms of (cryptic but) correct English, with
91
16. Do not use /* .... */ : not for code because all such code
92
should have been removed in the first place (point 7), and not
93
for comments since intent is more obvious if all comment lines
96
17. Indent two further steps for each new logical substructure
97
(loops, conditional statements, etc.). The namespace {, public:
98
and private: are exceptions to this rule, requiring no extra
101
18. Do not use tabs for formatting; it may give a mess when read by
104
19. Use exactly one space to separate logical structures and operators:
106
If readibility can be improved by lining up nearby statements then
107
this is allowed to take precedence, however:
111
20. One area of inconsistency is whether a blank is used after ( or not:
112
void status(int statusIn) {statusSave = statusIn;}
113
virtual void set1Kin( double x1in, double x2in, double sHin);
114
If there is a thought, it is that for short constructions a blank
115
tends to unnecessarily break up the structure, while for longer ones
116
such breaks are necessary to gain overview. Similarly ( ( may often
117
be used to give better structure than ((.
119
21. Allow several statements on the same line in header files, since
120
operations here should be simple and short. Avoid it in .cc files,
121
where one may want to more carefully study the logical structure,
122
and could more easily miss statements that way.
124
22. Do not use pointers more than you absolutely need to. For most usage
125
a reference is much nicer, but unfortunetely it cannot be saved.
126
If you need a pointer, have its name end with Ptr, so it is easily
127
recognized. In declarations the * goes with the pointer type:
129
rather than e.g. Info *infoPtr.
131
23. Class names should begin with a capital letter, whereas instances of
132
this class begin lowercase. Also methods and local variable names
133
should begin lowercase. Only static const VARIABLENAME are given in
134
uppercase throughout.
136
24. Use capitalization inside a word to help reading, e.g.
137
pAbs, toCMframe, useNewBeamShape, skipInit.
138
Descriptive names are helpful, but don't make them longer than
139
they have to (thisVariableSumsAllDiagonalMatrixElements is better
140
replaced by sumDiag).
142
25. It is useful if index names begin with an i (or j, k if several
143
are needed) and sizes with an n.
145
26. Pick ++i instead of i++, unless the latter is intentional.
146
Recall that ++i is updated at the point it is encountered,
147
while i++ implies it need only be updated after other operations
148
have taken place, which can be confusing.
150
27. Use int for all integers, except where potential overflow warrants
151
long, and avoid unsigned integers.
153
28. Use double for all real variables.
155
29. Use the Pythia complex type for all complex variables, defined by
156
typedef std::complex<double> complex;
159
30. Use the Pythia Vec4 class for four-vectors.
161
31. Use string for all text, except when C++ leaves you no option but
162
to use char or char*, e.g. for the name of a file to be opened.
164
32. Use the Boolean operators &&, || and !, not the alternative old
165
cleartext "and", "or" and "not".
167
33. Do not use cast notation where function style is possible,
168
i.e. int i = int(r); rather than int i = (int)r;.
170
34. Do not use typedef (except in point 29 above).
172
35. Units of GeV for energies and mm for distances are implicit,
173
with c = 1 so the same units can be used for momentum, mass
176
36. If an expression needs to be split over lines, let the new line
177
begin with an operator, so that the reason for several lines is
179
double sum = a + b + c + d
182
double sum = a + b + c + d
184
(i.e. lined-up or indented-two-steps, whatever is most convenient).
186
37. Be very restrictive with output from your methods. Some limited
187
initialization info may be relevant, but desist if you can.
188
During running printing should either be located in special methods
189
that the user has to call explicitly (with ostream& os = cout as
190
last argument) or, for error messages, make use of the
191
Info::errorMsg(..) method.
193
38. No global variables. It should be possible to have several
194
instances of Pythia running without any risk of interference
197
39. Do not have a { on a line of its own, but allow a lone } at
198
the very end of the conditions/loops (or, for longer pieces of
199
code, at the end of each conditions case):
206
40. Use the standard constant M_PI for the value of pi = 3.141592...
208
41. Use pow2(double), pow3(double), pow4(double), pow5(double) and
209
pow6(double) for small positive integer powers, since the standard
210
pow(double, double) can be very slow for such operations.
212
42. The event record, both the process and event ones, are always
213
passed as references rather than pointers. This allows notation
214
like event[i].p() rather than (*eventPtr)[i].p(); note that
215
eventPtr[i]->p() is not allowed C++ notation.
217
43. Use standard names for some of the other class instances, like
218
infoPtr, particleDataPtr, rndmPtr, beamAPtr, beamBPtr, couplingsPtr,
219
partonSystemsPtr, userHooksPtr, etc..The Settings database is normally
220
only interrogated during initializations, so is usually passad as
221
reference settings rather than pointer settingsPtr.
223
-----------------------------------------------------------------------
225
Remember to update the xmldoc documentation in parallel with the
226
code updates. All the details should make it directly into the
227
respective webpage, with UpdateHistory.xml only giving a very
228
brief summary. (This is different from Pythia 6, where the update
229
notes had to be complete.)
231
The xml notes are not intended to be read by users, who instead will
232
access the html and php equivalents. The translation from xml to
233
html and php is done with a specially written conversion program.
234
This program is not distributed with the code, to avoid abuse by
235
users, but will be run from time to time. The program handles a set
236
of new tags, and additionally you can use many standard html ones,
237
which are passed on without any action.
239
Outlined below is the set of xml tags in current use, that are
240
covered by a translation program. Also a few other open issues.
242
We try to stick with xml rules, e.g. <tag>...</tag> for pair
243
and <tag/> for single (=combined begin+end). Note that the parsing
244
of the conversion program assumes a "sensible" layout of the text.
246
A) Standard html concepts:
247
<h1></h1> a top-level header;
248
<h2></h2> a subheader;
249
<h3></h3> a subsubheader;
250
<h4></h4> a subsubsubheader;
252
<p/> a new paragraph;
253
<ol></ol> an ordered list, with <li> items;
254
<ul></ul> a bulleted list, with <li> items;
255
<li></li> an item in an ordered or bulleted list;
256
<dl></dl> a definition list (used for references);
257
<dt></dt> a definition term in a definition list;
258
<dd></dd> a definition text in a definition list;
260
<i></i> italics - will be used for typesetting formulae so avoid for text;
261
<code></code> inline computer code (teletype font);
262
<pre></pre> a piece of code, with linebreaks as formatted (teletype font);
263
<a href="..." target="..."></a> anchor;
264
<frameset ....></frameset> : only used in Welcome.xml;
265
<frame ....></frame> : only used in Welcome.xml;
266
<img src="..." alt="..." hspace=... /> only used in Index.xml;
267
<table</table> and <td></td> around SaveSettings dialog box.
269
B) New concepts for simple markup (no interactivity):
270
<chapter name="..."></chapter> a large chunk of text,
271
stored as one single xml file;
272
<eq></eq> text to be displayed on a separate line, centered if possible
273
(a poor man's equation), maybe typeset in italics (<i>);
274
<ei></ei> inline variant of above;
275
<note></note> text begun on new line, in boldface;
276
<notenl></notenl> text begun, no linebreak, in boldface;
277
<file name="..."></file> name of a program file (new paragraph, boldface);
278
<class name="..."></class> information on a specific class,
279
specifically the class creation command form;
280
<method name="..."></method> explanation of a class method;
281
<methodmore name="..."></methodmore> a class method to be listed closely
282
together with the previous one, since they belong together;
283
<argument name="..." default="..."></argument> an argument of
284
the class creation or another method in the class, optionally
285
with a default value:
286
<argoption value="..."></argoption> further explanation of an
287
allowed option of an argument.
289
C) New concepts for user interaction in php files (but no interactivity
292
reference to an article; replaced by [...] and anchor;
293
<aloc href="..."></aloc>
294
anchor among local pages; automatically fills with file type and
296
<aidx href="..."></aidx>
297
anchor from Index.xml to other files; automatically fills with
298
file type and target="page";
299
<flag name="..." default="..."></flag>
300
a switch to be used in the event generation; in php shown with
301
radio buttons to pick on (= yes, true) or off (= no, false),
302
written to file as a line with name = value;
303
<flagfix name="..." default="..."></flagfix>
304
ditto but no interactivity;
305
<modeopen name="..." default="..." min="..." max="..."></modeopen>
306
an integer value to be used in the event generation; in php
307
shown as a dialogue box where an integer can be typed in, and
308
written to file as a line with name = value; the min and max values
310
<modepick name="..." default="..." min="..." max="..."></modepick>
311
an integer value to be used in the event generation; unlike modeopen
312
above there is a fixed set of <option>'s available, in php shown
313
with radio buttons to pick one of them, written to file as a line
314
with name = value; the min and max values are optional;
315
<option value="..."></option>
316
a discrete set of options for a <modepick>, see above;
317
<modefix name="..." default="..." min="..." max="..."></modeopen>
318
ditto but no interactivity;
319
<parm name="..." default="..." min="..." max="..."></parm>
320
a double-precision value to be used in the event generation; in php
321
shown as a dialogue box where a real number can be typed in, and
322
written to file as a line with name = value; the min and max values
324
<parmfix name="..." default="..." min="..." max="..."></parm>
325
ditto but no interactivity;
326
<word name="..." default="..."></word>
327
a character string, without blanks, to be used in the event generation
328
mainly for file names; in php shown as a dialogue box where text can be
329
typed in, and written to file as a line with name = value;
330
<wordfix name="..." default="..."></wordfix>
331
ditto but no interactivity;
333
D) New concepts that could one day be made interactive, but currently
335
<particle id="..." name="..." antiName="..." spinType="..."
336
chargeType="..." colType="..." m0="..." mWidth="..." mMin="..."
337
mMax="..." tau0="..."></particle>
338
the properties of a particle, most of which are optional;
339
<channel onMode="..." bRatio="..." meMode="..." products="..."/></channel>
340
the properties of a decay channel; this tag can only appear inside a
341
<particle>...</particle> block; the meMode field is optional; the
342
products appear as a blank-separated list.
added
removed
CODINGSTYLE
