CMake: removing qpythia from the depedencies
[u/mrichter/AliRoot.git] / PYTHIA8 / pythia8175 / CODINGSTYLE
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.