1 | Coding Style |
---|
2 | |
---|
3 | This file is only intended for contributors of code to Pythia 8. |
---|
4 | As a normal user you need not read it. |
---|
5 | |
---|
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. |
---|
11 | |
---|
12 | Remember to update the xmldoc documentation in parallel with the |
---|
13 | code updates. The xml rules are provided after the coding rules. |
---|
14 | |
---|
15 | ----------------------------------------------------------------------- |
---|
16 | |
---|
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. |
---|
20 | |
---|
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.) |
---|
24 | |
---|
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. |
---|
28 | |
---|
29 | 3. English is the only allowed language (for comments, variable |
---|
30 | names, etc.). |
---|
31 | |
---|
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. |
---|
36 | |
---|
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. |
---|
42 | |
---|
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. |
---|
46 | |
---|
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. |
---|
51 | |
---|
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. |
---|
62 | |
---|
63 | 9. Use lines |
---|
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. |
---|
67 | |
---|
68 | 10. Use lines |
---|
69 | //-------------------------------------------------------------------------- |
---|
70 | for smaller subdivisions than above. Specifically, in .cc files, |
---|
71 | insert it between the different methods that belong to the same |
---|
72 | class. |
---|
73 | |
---|
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. |
---|
77 | |
---|
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. |
---|
81 | |
---|
82 | 13. Comment lines may also precede a particularly crucial statement |
---|
83 | inside a code chunk, without the need for a blank line before. |
---|
84 | |
---|
85 | 14. Do not add comments on the same line as a statement: |
---|
86 | a = b + c; // No comment here! |
---|
87 | |
---|
88 | 15. Write comments in terms of (cryptic but) correct English, with |
---|
89 | relevant punctuation. |
---|
90 | |
---|
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 |
---|
94 | begin with //. |
---|
95 | |
---|
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 |
---|
99 | indentation. |
---|
100 | |
---|
101 | 18. Do not use tabs for formatting; it may give a mess when read by |
---|
102 | another user. |
---|
103 | |
---|
104 | 19. Use exactly one space to separate logical structures and operators: |
---|
105 | if (a == b) then { |
---|
106 | If readibility can be improved by lining up nearby statements then |
---|
107 | this is allowed to take precedence, however: |
---|
108 | int iNew = 0; |
---|
109 | double pm = 0.; |
---|
110 | |
---|
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 ((. |
---|
118 | |
---|
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. |
---|
123 | |
---|
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: |
---|
128 | Info* infoPtr; |
---|
129 | rather than e.g. Info *infoPtr. |
---|
130 | |
---|
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. |
---|
135 | |
---|
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). |
---|
141 | |
---|
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. |
---|
144 | |
---|
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. |
---|
149 | |
---|
150 | 27. Use int for all integers, except where potential overflow warrants |
---|
151 | long, and avoid unsigned integers. |
---|
152 | |
---|
153 | 28. Use double for all real variables. |
---|
154 | |
---|
155 | 29. Use the Pythia complex type for all complex variables, defined by |
---|
156 | typedef std::complex<double> complex; |
---|
157 | in PythiaComplex.h |
---|
158 | |
---|
159 | 30. Use the Pythia Vec4 class for four-vectors. |
---|
160 | |
---|
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. |
---|
163 | |
---|
164 | 32. Use the Boolean operators &&, || and !, not the alternative old |
---|
165 | cleartext "and", "or" and "not". |
---|
166 | |
---|
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;. |
---|
169 | |
---|
170 | 34. Do not use typedef (except in point 29 above). |
---|
171 | |
---|
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 |
---|
174 | and time. |
---|
175 | |
---|
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 |
---|
178 | apparent: |
---|
179 | double sum = a + b + c + d |
---|
180 | + e + f + g; |
---|
181 | alternatively |
---|
182 | double sum = a + b + c + d |
---|
183 | + e + f + g; |
---|
184 | (i.e. lined-up or indented-two-steps, whatever is most convenient). |
---|
185 | |
---|
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. |
---|
192 | |
---|
193 | 38. No global variables. It should be possible to have several |
---|
194 | instances of Pythia running without any risk of interference |
---|
195 | between them. |
---|
196 | |
---|
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): |
---|
200 | if (isCharged) { |
---|
201 | statements; |
---|
202 | } else { |
---|
203 | more statements; |
---|
204 | } |
---|
205 | |
---|
206 | 40. Use the standard constant M_PI for the value of pi = 3.141592... |
---|
207 | |
---|
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. |
---|
211 | |
---|
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. |
---|
216 | |
---|
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. |
---|
222 | |
---|
223 | 44. Only use == and != for comparisons between two pointers, |
---|
224 | or a pointer and 0. Thus comparisons like (Xptr > 0) are forbidden. |
---|
225 | |
---|
226 | ----------------------------------------------------------------------- |
---|
227 | |
---|
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.) |
---|
233 | |
---|
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. |
---|
241 | |
---|
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. |
---|
244 | |
---|
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. |
---|
248 | |
---|
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; |
---|
254 | <br/> a new line; |
---|
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; |
---|
262 | <b></b> boldface; |
---|
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. |
---|
271 | |
---|
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. |
---|
291 | |
---|
292 | C) New concepts for user interaction in php files (but no interactivity |
---|
293 | in html): |
---|
294 | <ref></ref> |
---|
295 | reference to an article; replaced by [...] and anchor; |
---|
296 | <aloc href="..."></aloc> |
---|
297 | anchor among local pages; automatically fills with file type and |
---|
298 | target="page"; |
---|
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 |
---|
312 | are optional; |
---|
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 |
---|
326 | are optional; |
---|
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; |
---|
335 | |
---|
336 | D) New concepts that could one day be made interactive, but currently |
---|
337 | are not: |
---|
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. |
---|