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) 2017 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 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. ... for pair and for single (=combined begin+end). Note that the parsing of the conversion program assumes a "sensible" layout of the text. A) Standard html concepts:

a top-level header;

a subheader;

a subsubheader;

a subsubsubheader;
a new line;

a new paragraph;

    an ordered list, with
  1. items;
      a bulleted list, with
    • items;
    • an item in an ordered or bulleted list;
      a definition list (used for references);
      a definition term in a definition list;
      a definition text in a definition list; boldface; italics - will be used for typesetting formulae so avoid for text; inline computer code (teletype font); 
       a piece of code, with linebreaks as formatted (teletype font);
 anchor;
 : only used in Welcome.xml;
 : only used in Welcome.xml;
... only used in Index.xml;
 and  around SaveSettings dialog box.

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

C) New concepts for user interaction in php files (but no interactivity
in html):

    reference to an article; replaced by [...] and anchor;

    anchor among local pages; automatically fills with file type and
    target="page";

    anchor from Index.xml to other files; automatically fills with
    file type and target="page";

    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;

    ditto but no interactivity;

    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;

    an integer value to be used in the event generation; unlike modeopen
    above there is a fixed set of 
    a discrete set of options for a , see above;

    ditto but no interactivity;

    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;

    ditto but no interactivity;

    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;

    ditto but no interactivity;

D) New concepts that could one day be made interactive, but currently
are not:

    the properties of a particle, most of which are optional;

    the properties of a decay channel; this tag can only appear inside a
    ... block; the meMode field is optional; the
    products appear as a blank-separated list.