Merge branch 'master' of https://git.cern.ch/reps/AliRoot

[u/mrichter/AliRoot.git] / PYTHIA8 / pythia8175 / CODINGSTYLE

Coding Style

This file is only intended for contributors of code to Pythia 8. 
As a normal user you need not read it.

A reasonably consistent coding style enhances readability and 
understanding of code, so do take the time to make new code 
blend smoothly with the existing structure. That said, complete
consistency is impossible, and style must always come second to
content. So any rules should be applied with common sense. 

Remember to update the xmldoc documentation in parallel with the 
code updates. The xml rules are provided after the coding rules.

-----------------------------------------------------------------------

For the Pythia8 code some principles have been used, some by
deliberate decision, while others evolved organically. 
An incomplete list is as follows.

 1. Use existing files to get a feel for the general outlay. 
    (Especially the "core" files that have set the standard for
    later writing, e.g. Pythia, Event, or Basics.)  

 2. Use standard C++, in a clear and consistent manner. Do not 
    show off by using special tricks that only experts will 
    appreciate. Do not use any experimental language features. 

 3. English is the only allowed language (for comments, variable
    names, etc.).

 4. Lines should be at most 79 characters long, so that they do 
    not overflow when opened in an 80 characters wide text editor
    window. This number includes any trailing blanks, another
    "feature" that should be avoided. 
 
 5. Never make code dependent on the presence of external libraries.
    Some libraries, like LHAPDF and HepMC are already interfaced,
    but only in well-defined non-critical manners. If you want to
    include interfaces to new libraries, or modify the existing ones,
    you should bring it up for open discussion beforehand.

 6. The underscore "character" should be avoided as far as possible;
    it makes code difficult to read. See also point 24. Currently it 
    is only used in headers, for #ifndef Pythia8_filename_H. 

 7. Extra code used for debugging purposes, or left behind from
    the development process, even if commented out, should be
    removed from the public version. Feel free to save your own 
    private versions where such code is available.

 8. Begin each code file with 
// (filename) is a part of the PYTHIA event generator.
// Copyright (C) 2013 Torbjorn Sjostrand.
// PYTHIA is licenced under the GNU GPL version 2, see COPYING for details.
// Please respect the MCnet Guidelines, see GUIDELINES for details.
    to establish the legal structure. Follow that with specific
    information on authorship of the particular file, where relevant,
    and a very brief summary of the contents. After that follow with
    #include and other preprocessor commands and namespace Pythia8 {, 
    before the actual code. 

 9. Use lines  
//==========================================================================
    to separate classes from each other, and from top and bottom 
    material of a file, that does not belong to a class.

10. Use lines
//--------------------------------------------------------------------------
    for smaller subdivisions than above. Specifically, in .cc files,
    insert it between the different methods that belong to the same
    class. 

11. Blank lines should be used to separate the code into suitable
    chunks of statements that belong together. Never use two or
    more blank lines consecutively, however.

12. Begin each code chunk with one or more comment lines that 
    explains the purpose of this chunk. Do not overdo documentation,
    however: the purpose is to provide overview, not clutter.
 
13. Comment lines may also precede a particularly crucial statement
    inside a code chunk, without the need for a blank line before.

14. Do not add comments on the same line as a statement:
       a = b + c;   // No comment here!  

15. Write comments in terms of (cryptic but) correct English, with
    relevant punctuation.

16. Do not use /* .... */ : not for code because all such code 
    should have been removed in the first place (point 7), and not 
    for comments since intent is more obvious if all comment lines
    begin with //.
  
17. Indent two further steps for each new logical substructure
    (loops, conditional statements, etc.). The namespace {, public:
    and private: are exceptions to this rule, requiring no extra
    indentation. 

18. Do not use tabs for formatting; it may give a mess when read by 
    another user. 

19. Use exactly one space to separate logical structures and operators:
    if (a == b) then {
    If readibility can be improved by lining up nearby statements then
    this is allowed to take precedence, however:
    int    iNew = 0;
    double pm   = 0.;
 
20. One area of inconsistency is whether a blank is used after ( or not:
    void status(int statusIn) {statusSave = statusIn;}
    virtual void set1Kin( double x1in, double x2in, double sHin);
    If there is a thought, it is that for short constructions a blank
    tends to unnecessarily break up the structure, while for longer ones
    such breaks are necessary to gain overview. Similarly ( ( may often
    be used to give better structure than ((.

21. Allow several statements on the same line in header files, since
    operations here should be simple and short. Avoid it in .cc files,
    where one may want to more carefully study the logical structure,
    and could more easily miss statements that way.

22. Do not use pointers more than you absolutely need to. For most usage
    a reference is much nicer, but unfortunetely it cannot be saved.
    If you need a pointer, have its name end with Ptr, so it is easily
    recognized. In declarations the * goes with the pointer type:
    Info* infoPtr;  
    rather than e.g. Info *infoPtr. 

23. Class names should begin with a capital letter, whereas instances of
    this class begin lowercase. Also methods and local variable names 
    should begin lowercase. Only static const VARIABLENAME are given in 
    uppercase throughout. 

24. Use capitalization inside a word to help reading, e.g.
    pAbs, toCMframe, useNewBeamShape, skipInit.
    Descriptive names are helpful, but don't make them longer than 
    they have to (thisVariableSumsAllDiagonalMatrixElements is better
    replaced by sumDiag).

25. It is useful if index names begin with an i (or j, k if several 
    are needed) and sizes with an n.
 
26. Pick ++i instead of i++, unless the latter is intentional.
    Recall that ++i is updated at the point it is encountered, 
    while i++ implies it need only be updated after other operations
    have taken place, which can be confusing.

27. Use int for all integers, except where potential overflow warrants
    long, and avoid unsigned integers. 

28. Use double for all real variables.

29. Use the Pythia complex type for all complex variables, defined by
    typedef std::complex<double> complex;
    in PythiaComplex.h

30. Use the Pythia Vec4 class for four-vectors.

31. Use string for all text, except when C++ leaves you no option but
    to use char or char*, e.g. for the name of a file to be opened.

32. Use the Boolean operators &&, || and !, not the alternative old
    cleartext "and", "or" and "not".

33. Do not use cast notation where function style is possible,
    i.e. int i = int(r); rather than int i = (int)r;.

34. Do not use typedef (except in point 29 above). 

35. Units of GeV for energies and mm for distances are implicit,
    with c = 1 so the same units can be used for momentum, mass 
    and time.

36. If an expression needs to be split over lines, let the new line
    begin with an operator, so that the reason for several lines is 
    apparent:
    double sum = a + b + c + d
               + e + f + g;
    alternatively
    double sum = a + b + c + d
      + e + f + g;
    (i.e. lined-up or indented-two-steps, whatever is most convenient). 

37. Be very restrictive with output from your methods. Some limited
    initialization info may be relevant, but desist if you can.
    During running printing should either be located in special methods 
    that the user has to call explicitly (with ostream& os = cout as 
    last argument) or, for error messages, make use of the 
    Info::errorMsg(..) method.

38. No global variables. It should be possible to have several 
    instances of Pythia running without any risk of interference
    between them. 

39. Do not have a { on a line of its own, but allow a lone } at
    the very end of the conditions/loops (or, for longer pieces of 
    code, at the end of each conditions case):
    if (isCharged) {
      statements;
    } else {
      more statements; 
    } 

40. Use the standard constant M_PI for the value of pi = 3.141592...

41. Use pow2(double), pow3(double), pow4(double), pow5(double) and 
    pow6(double) for small positive integer powers, since the standard
    pow(double, double) can be very slow for such operations.

42. The event record, both the process and event ones, are always 
    passed as references rather than pointers. This allows notation 
    like event[i].p() rather than (*eventPtr)[i].p(); note that 
    eventPtr[i]->p() is not allowed C++ notation. 

43. Use standard names for some of the other class instances, like
    infoPtr, particleDataPtr, rndmPtr, beamAPtr, beamBPtr, couplingsPtr,
    partonSystemsPtr, userHooksPtr, etc..The Settings database is normally
    only interrogated during initializations, so is usually passad as
    reference settings rather than pointer settingsPtr.

44. Only use == and != for comparisons between two pointers,  
    or a pointer and 0. Thus comparisons like (Xptr > 0) are forbidden.

-----------------------------------------------------------------------

Remember to update the xmldoc documentation in parallel with the 
code updates. All the details should make it directly into the 
respective webpage, with UpdateHistory.xml only giving a very 
brief summary. (This is different from Pythia 6, where the update
notes had to be complete.)

The xml notes are not intended to be read by users, who instead will
access the html and php equivalents. The translation from xml to 
html and php is done with a specially written conversion program.
This program is not distributed with the code, to avoid abuse by 
users, but will be run from time to time. The program handles a set
of new tags, and additionally you can use many standard html ones,
which are passed on without any action. 

Outlined below is the set of xml tags in current use, that are 
covered by a translation program. Also a few other open issues.

We try to stick with xml rules, e.g. <tag>...</tag> for pair
and <tag/> for single (=combined begin+end). Note that the parsing 
of the conversion program assumes a "sensible" layout of the text. 

A) Standard html concepts:
<h1></h1> a top-level header;
<h2></h2> a subheader;
<h3></h3> a subsubheader;
<h4></h4> a subsubsubheader;
<br/> a new line;
<p/> a new paragraph;
<ol></ol> an ordered list, with <li> items;
<ul></ul> a bulleted list, with <li> items;
<li></li> an item in an ordered or bulleted list;
<dl></dl> a definition list (used for references);
<dt></dt> a definition term in a definition list;
<dd></dd> a definition text in a definition list;
<b></b> boldface;
<i></i> italics - will be used for typesetting formulae so avoid for text;
<code></code> inline computer code (teletype font);
<pre></pre> a piece of code, with linebreaks as formatted (teletype font); 
<a href="..." target="..."></a> anchor;
<frameset ....></frameset> : only used in Welcome.xml;
<frame ....></frame> : only used in Welcome.xml;
<img src="..." alt="..." hspace=... /> only used in Index.xml;
<table</table> and <td></td> around SaveSettings dialog box.

B) New concepts for simple markup (no interactivity):
<chapter name="..."></chapter> a large chunk of text, 
    stored as one single xml file;
<eq></eq> text to be displayed on a separate line, centered if possible 
    (a poor man's equation), maybe typeset in italics (<i>);
<ei></ei> inline variant of above;
<note></note> text begun on new line, in boldface;
<notenl></notenl> text begun, no linebreak, in boldface;
<file name="..."></file> name of a program file (new paragraph, boldface);
<class name="..."></class> information on a specific class,
    specifically the class creation command form;
<method name="..."></method> explanation of a class method;
<methodmore name="..."></methodmore> a class method to be listed closely
    together with the previous one, since they belong together;
<argument name="..." default="..."></argument> an argument of 
    the class creation or another method in the class, optionally 
    with a default value:
<argoption value="..."></argoption> further explanation of an 
    allowed option of an argument.   

C) New concepts for user interaction in php files (but no interactivity 
in html):
<ref></ref> 
    reference to an article; replaced by [...] and anchor;
<aloc href="..."></aloc> 
    anchor among local pages; automatically fills with file type and
    target="page";
<aidx href="..."></aidx> 
    anchor from Index.xml to other files; automatically fills with 
    file type and target="page";
<flag name="..." default="..."></flag> 
    a switch to be used in the event generation; in php shown with 
    radio buttons to pick on (= yes, true) or off (= no, false), 
    written to file as a line with name = value; 
<flagfix name="..." default="..."></flagfix>
    ditto but no interactivity;
<modeopen name="..." default="..." min="..." max="..."></modeopen>
    an integer value to be used in the event generation; in php
    shown as a dialogue box where an integer can be typed in, and
    written to file as a line with name = value; the min and max values 
    are optional; 
<modepick name="..." default="..." min="..." max="..."></modepick>
    an integer value to be used in the event generation; unlike modeopen 
    above there is a fixed set of <option>'s available, in php shown 
    with radio buttons to pick one of them, written to file as a line 
    with name = value; the min and max values are optional; 
<option value="..."></option>
    a discrete set of options for a <modepick>, see above;
<modefix name="..." default="..." min="..." max="..."></modeopen>
    ditto but no interactivity;
<parm name="..." default="..." min="..." max="..."></parm>
    a double-precision value to be used in the event generation; in php
    shown as a dialogue box where a real number can be typed in, and
    written to file as a line with name = value; the min and max values 
    are optional; 
<parmfix name="..." default="..." min="..." max="..."></parm>
    ditto but no interactivity;
<word name="..." default="..."></word>
    a character string, without blanks, to be used in the event generation
    mainly for file names; in php shown as a dialogue box where text can be 
    typed in, and written to file as a line with name = value;
<wordfix name="..." default="..."></wordfix>
    ditto but no interactivity;

D) New concepts that could one day be made interactive, but currently 
are not:
<particle id="..." name="..." antiName="..." spinType="..." 
    chargeType="..." colType="..." m0="..." mWidth="..." mMin="..." 
    mMax="..." tau0="..."></particle>
    the properties of a particle, most of which are optional;
<channel onMode="..." bRatio="..." meMode="..." products="..."/></channel>
    the properties of a decay channel; this tag can only appear inside a
    <particle>...</particle> block; the meMode field is optional; the
    products appear as a blank-separated list.