]>
Commit | Line | Data |
---|---|---|
c6b60c38 | 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) 2013 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. |