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 44. Only use == and != for comparisons between two pointers,
224 or a pointer and 0. Thus comparisons like (Xptr > 0) are forbidden.
226 -----------------------------------------------------------------------
228 Remember to update the xmldoc documentation in parallel with the
229 code updates. All the details should make it directly into the
230 respective webpage, with UpdateHistory.xml only giving a very
231 brief summary. (This is different from Pythia 6, where the update
232 notes had to be complete.)
234 The xml notes are not intended to be read by users, who instead will
235 access the html and php equivalents. The translation from xml to
236 html and php is done with a specially written conversion program.
237 This program is not distributed with the code, to avoid abuse by
238 users, but will be run from time to time. The program handles a set
239 of new tags, and additionally you can use many standard html ones,
240 which are passed on without any action.
242 Outlined below is the set of xml tags in current use, that are
243 covered by a translation program. Also a few other open issues.
245 We try to stick with xml rules, e.g. <tag>...</tag> for pair
246 and <tag/> for single (=combined begin+end). Note that the parsing
247 of the conversion program assumes a "sensible" layout of the text.
249 A) Standard html concepts:
250 <h1></h1> a top-level header;
251 <h2></h2> a subheader;
252 <h3></h3> a subsubheader;
253 <h4></h4> a subsubsubheader;
255 <p/> a new paragraph;
256 <ol></ol> an ordered list, with <li> items;
257 <ul></ul> a bulleted list, with <li> items;
258 <li></li> an item in an ordered or bulleted list;
259 <dl></dl> a definition list (used for references);
260 <dt></dt> a definition term in a definition list;
261 <dd></dd> a definition text in a definition list;
263 <i></i> italics - will be used for typesetting formulae so avoid for text;
264 <code></code> inline computer code (teletype font);
265 <pre></pre> a piece of code, with linebreaks as formatted (teletype font);
266 <a href="..." target="..."></a> anchor;
267 <frameset ....></frameset> : only used in Welcome.xml;
268 <frame ....></frame> : only used in Welcome.xml;
269 <img src="..." alt="..." hspace=... /> only used in Index.xml;
270 <table</table> and <td></td> around SaveSettings dialog box.
272 B) New concepts for simple markup (no interactivity):
273 <chapter name="..."></chapter> a large chunk of text,
274 stored as one single xml file;
275 <eq></eq> text to be displayed on a separate line, centered if possible
276 (a poor man's equation), maybe typeset in italics (<i>);
277 <ei></ei> inline variant of above;
278 <note></note> text begun on new line, in boldface;
279 <notenl></notenl> text begun, no linebreak, in boldface;
280 <file name="..."></file> name of a program file (new paragraph, boldface);
281 <class name="..."></class> information on a specific class,
282 specifically the class creation command form;
283 <method name="..."></method> explanation of a class method;
284 <methodmore name="..."></methodmore> a class method to be listed closely
285 together with the previous one, since they belong together;
286 <argument name="..." default="..."></argument> an argument of
287 the class creation or another method in the class, optionally
288 with a default value:
289 <argoption value="..."></argoption> further explanation of an
290 allowed option of an argument.
292 C) New concepts for user interaction in php files (but no interactivity
295 reference to an article; replaced by [...] and anchor;
296 <aloc href="..."></aloc>
297 anchor among local pages; automatically fills with file type and
299 <aidx href="..."></aidx>
300 anchor from Index.xml to other files; automatically fills with
301 file type and target="page";
302 <flag name="..." default="..."></flag>
303 a switch to be used in the event generation; in php shown with
304 radio buttons to pick on (= yes, true) or off (= no, false),
305 written to file as a line with name = value;
306 <flagfix name="..." default="..."></flagfix>
307 ditto but no interactivity;
308 <modeopen name="..." default="..." min="..." max="..."></modeopen>
309 an integer value to be used in the event generation; in php
310 shown as a dialogue box where an integer can be typed in, and
311 written to file as a line with name = value; the min and max values
313 <modepick name="..." default="..." min="..." max="..."></modepick>
314 an integer value to be used in the event generation; unlike modeopen
315 above there is a fixed set of <option>'s available, in php shown
316 with radio buttons to pick one of them, written to file as a line
317 with name = value; the min and max values are optional;
318 <option value="..."></option>
319 a discrete set of options for a <modepick>, see above;
320 <modefix name="..." default="..." min="..." max="..."></modeopen>
321 ditto but no interactivity;
322 <parm name="..." default="..." min="..." max="..."></parm>
323 a double-precision value to be used in the event generation; in php
324 shown as a dialogue box where a real number can be typed in, and
325 written to file as a line with name = value; the min and max values
327 <parmfix name="..." default="..." min="..." max="..."></parm>
328 ditto but no interactivity;
329 <word name="..." default="..."></word>
330 a character string, without blanks, to be used in the event generation
331 mainly for file names; in php shown as a dialogue box where text can be
332 typed in, and written to file as a line with name = value;
333 <wordfix name="..." default="..."></wordfix>
334 ditto but no interactivity;
336 D) New concepts that could one day be made interactive, but currently
338 <particle id="..." name="..." antiName="..." spinType="..."
339 chargeType="..." colType="..." m0="..." mWidth="..." mMin="..."
340 mMax="..." tau0="..."></particle>
341 the properties of a particle, most of which are optional;
342 <channel onMode="..." bRatio="..." meMode="..." products="..."/></channel>
343 the properties of a decay channel; this tag can only appear inside a
344 <particle>...</particle> block; the meMode field is optional; the
345 products appear as a blank-separated list.