view CODINGSTYLE @ 1110:2ba52dbf2312

Add release instructions for new sets
author Andy Buckley <andy@insectnation.org>
date Tue, 17 Oct 2017 17:12:04 +0100
parents d18954371da9
line source
1 /**
2 @page codingstyle Coding style
5 =======================
7 A short guide for developers and patch suppliers on the C++ coding style used in
8 LHAPDF >= 6.
10 - The basic style is the ["one true brace style"](http://en.wikipedia.org/wiki/Indent_style#Variant:_1TBS).
11 The exception is for constructors with initialisation lists, in which case the
12 function body should be opened by a brace on its own on a new line, rather
13 than the brace trailing the init list entries.
15 - Indent! The standard indent size in the current code is two spaces. Do not
16 indent with tab characters.
18 - Infix operators like = (assignment), logical comparators (==, !=, >, <, >=,
19 etc.), + and -, and all arithmetic modifying operators (+=, -=, *=, /=) should
20 be separated from their arguments on either side by a single space. Spaces are
21 cheap, the time taken to decipher hyper-compressed code is not! The * and /
22 operators should be padded like this if it aids readability, but not
23 otherwise: it is useful to visually distinguish addition of terms from the
24 multiplications/divisions which compose them.
26 - The parenthetical condition statement of an "if", "for", "while", etc. block
27 should be separated from the "if" etc. keyword and from the opening brace of
28 the block by one space. The contents of the parenthesis should not be
29 space-padded, however, unless it is necessary for clarity (the same applies to
30 function arguments). For example, "if (foo > bar) { ...". Again, spaces are
31 cheap: use them.
33 - Braces are encouraged around all but the most trivial control blocks: if you
34 cannot put the one-line block content on the *same* line as the block
35 condition statement, or if there is any visual ambiguity about which lines are
36 in the block body, add braces.
38 - if-statement and exception continuations should normally be on the same line
39 as the delimiting braces in 1TBS fashion, e.g. "} else {", "} else if (foo !=
40 bar) {", etc.
42 - All code should be in the LHAPDF namespace. In .cc files, unnamed namespaces
43 should be used to hide implementation detail functions from public/ABI view.
45 - Class names are in CamelCase format, and method and function names in
46 lowerCamelCase. In the class names "PDF" is always kept fully capitalised,
47 while in method and function names it may appear as "pdf" or "Pdf" depending
48 on context: try to be consistent with the "local environment". Private or
49 protected members, or more generally any API element not designed for public
50 use should start with a leading underscore, cf. _implementationDetail.
52 - Separate blocks within functions by a blank line, separate functions by two
53 blank lines, and separate class definitions by 3 blank lines. Two blank lines
54 of separation should be left between the main LHAPDF namespace opening and
55 closing braces and the first and last code lines in the namespace. These are
56 just guidelines: if more lines of separation than these nominals are needed
57 for visual clearance of distinct code elements, add more: blank lines are also
58 pretty cheap, but don't go crazy or you'll hardly be able to fit any lines of
59 active code on your screen!
61 - Use the specialised LHAPDF exceptions from LHAPDF/Exceptions.h. Exceptions
62 should be used rather than asserts unless there is absolutely no way that the
63 tested condition could happen other than a bug in the system: the user should
64 be able to catch their own errors.
66 - We're relying on the Boost and yaml-cpp libraries, but currently no
67 others. Get a feel for what is available in Boost, and in the LHAPDF/Utils.h
68 header: do not reinvent the wheel.
70 - "Flavour" is spelt the American way, "flavor" in all places in the code, for
71 definiteness.
73 - Use comments! Describe what sections of not-immediately-clear code do in as
74 clear and concise a way as possible, preferably on one line. In header files
75 use Doxygen /// comments and operators with an @ delimiter (particularly "@todo")
76 to describe the meanings of classes, methods, their arguments, etc. While writing
77 code it's often best to leave some details until later -- mark these with a
78 "@todo" operator and a description of the missing feature: these will be collected
79 into a helpful list by Doxygen.
81 - If in doubt, ask!
85 */