|
| 1 | +#Naming |
| 2 | + |
| 3 | +The most important consistency rules are those that govern naming. The style of a name immediately informs us what sort of thing the named entity is: a type, a variable, a function, a macro, etc., without requiring us to search for the declaration of that entity. The pattern-matching engine in our brains relies a great deal on these naming rules. |
| 4 | + |
| 5 | +Naming rules are pretty arbitrary, but we feel that consistency is more important than individual preferences in this area, so regardless of whether you find them sensible or not, the rules are the rules. |
| 6 | + |
| 7 | +##General Naming Rules |
| 8 | +* Names should be meaningful; abbreviations should be avoided. They follow camel case convention. Types and variables, as well as access functions should be nouns, while functions should be "command" verbs. |
| 9 | + |
| 10 | +##Specific STAR Naming Rules |
| 11 | +* Each class name should begin with St and the appropriate three letter acronym (only first letter capitalized) to indicate its origin and prevent name clashes. |
| 12 | + |
| 13 | +##File Names |
| 14 | +* C++ code file names are derived from the class names. Following STAR's naming convention they hence always start with St. Each header file should contain only one or related class declarations for maintainability and for easier retrieval of class definitions. Files that contain only function code (e.g. Maker) and are unrelated to a specific class should start also with St followed by a descriptive name of the purpose of the code. |
| 15 | +##Type Names |
| 16 | +* Type names follow camel case convention and start with an upper case letter: MyClass, MyEnum. |
| 17 | +##Variable Names |
| 18 | +* Variable names follow camel case convention and start with a lower case letter: myLocalVariable. |
| 19 | + |
| 20 | + Class member variables are prefixed with m. |
| 21 | + No m prefix for struct members. |
| 22 | + Global variables are prefixed with g. |
| 23 | + constexpr variables are capitalized. |
| 24 | + No additional prefix for const. |
| 25 | + |
| 26 | +##Function Names |
| 27 | +* Regular functions follow camel case convention and start with a lower case letter: myFunction(). |
| 28 | + |
| 29 | + Accessors and mutators match the name of the variable. Accessors should follow the name of the variable (DO NOT prefix it with get) and mutators are prefixed with set, for example: myMemberVariable(), setMyMemberVariable(). |
| 30 | + Functions (including accessors) returning a boolean value should be prefixed with is or has. |
| 31 | + |
| 32 | +##Namespace Names |
| 33 | +* Namespace names follow camel case convention and start with an upper case letter: MyNamespace. |
| 34 | +##Enumerator Names |
| 35 | +* Enumerations and enumerators (the type and the values) follow camel case convention and start with St followed by an upper case letter: StBeamPolarizationAxis, StDetectorId. |
| 36 | + |
| 37 | + Enumerators in unscoped enumerations should have a common prefix/postfix derived from the enumerations name. |
| 38 | + Enum classes are already scoped and therefore the enumerators do not need a prefix/postfix. |
| 39 | + |
| 40 | +##Macro Names |
| 41 | +* All uppercase letters and underscores, prefixed with ST (for STAR) and the sub/project name, i.e. ST_PROJECT_PKG1_MY_MACRO. |
| 42 | +STAR StRoot Makers Naming Standards |
| 43 | +* This section attempts to explain the code directory structure and layout in STAR the rules and assumptions triggered in the make system (cons) solely on the basis of the name choice the existing exceptions to the rules. |
| 44 | + |
| 45 | +#Formatting |
| 46 | + |
| 47 | +Coding style and formatting are pretty arbitrary. However, a good project is much easier to follow if everyone uses the same style. Individuals may not agree with every aspect of the formatting rules, and some of the rules may be hard to get used to. Even so, it is important that all project contributors follow the style rules so that they can all read and understand everyone's code easily. |
| 48 | + |
| 49 | +##Line Length |
| 50 | +* Each line of text in your code should be at most 100 characters long. |
| 51 | +##One Statement Per Line |
| 52 | +* Prefer one statement per line because it improves code readability. |
| 53 | +## Spaces vs. Tabs |
| 54 | +* Indent code with at least 2 spaces. Prefer spaces over tabs. |
| 55 | +##Function Declarations and Definitions |
| 56 | +* A function declaration is on one line if possible. Otherwise the parameters that do not fit are on the next line(s). A function definition should not be part of the class declaration in the header file. Inline function should be defined in the header file but only below the class declaration. |
| 57 | +Pointer and Reference Expressions |
| 58 | +* No spaces around period or arrow. Pointer operators are either followed or preceded with a space. |
| 59 | +##Boolean Expressions |
| 60 | +* In the case of a boolean expression that is longer than the standard line length, lines should be broken up in a consistent way. All operators should be either at the beginning or at the end of the line. |
| 61 | +##Variable and Array Initialization |
| 62 | +* Prefer initialization with braces except for single-argument assignment. |
| 63 | +##Preprocessor Directives |
| 64 | +* The hash mark that starts a preprocessor directive is always at the beginning of the line. |
| 65 | +##Classes |
| 66 | +* Access specifiers in a class or a struct should not be indented. Lines containing methods and data member should be indented by at least 2 spaces, typically 4. Access specifiers should be ordered as public, protected, private. Declarations within a access specifier are to be ordered as Constructor, Destructor, Methods, Data Members. |
| 67 | +##Constructor Initializer Lists |
| 68 | +* Constructor initializer lists should be with subsequent lines indented properly. Alternatively, they can be all in a single line. |
| 69 | +##Namespaces |
| 70 | +* The contents of namespaces are not indented. |
| 71 | +##Braces |
| 72 | +* In control constructs (if statements, for loops etc.), it is recommended to use curly braces even when the body of the statement fits on one line. |
| 73 | +##Horizontal Whitespace |
| 74 | +* Recommended guidelines: |
| 75 | + |
| 76 | + One space should be used after each keyword. |
| 77 | + No extra spaces inside parenthesis and angle brackets (templates). |
| 78 | + Spaces should be used around binary operators. |
| 79 | + No space between a unary operator and its operand. |
| 80 | + Never put trailing whitespace at the end of a line. |
| 81 | + |
| 82 | +##Vertical Whitespace |
| 83 | +* Use only one empty line to separate code. |
| 84 | +##Where to put const |
| 85 | +* Put const before the type when defining a const variable. |
| 86 | +##Comments |
| 87 | + |
| 88 | +Though a pain to write, comments are absolutely vital to keeping our code readable. The following rules describe what you should comment and where. But remember: while comments are very important, the best code is self-documenting. Giving sensible names to types and variables is much better than using obscure names that you must then explain through comments. |
| 89 | + |
| 90 | +When writing your comments, write for your audience: the next contributor who will need to understand your code. Be generous — the next one may be you! |
| 91 | + |
| 92 | +##Comment Style |
| 93 | +* Use either the // or /* */ syntax, as long as you are consistent. |
| 94 | +##File Comment Block |
| 95 | +* Every file should have a comment at the top describing its contents. It should contains the CVS macros $Id$ and $Log$, the primary/original author, as well as a brief description of the class. |
| 96 | +##Function Comments |
| 97 | +* Declaration comments describe use of the function; comments at the definition of a function describe operation. |
| 98 | +##Variable Comments |
| 99 | +* In general the actual name of the variable should be descriptive enough to give a good idea of what the variable is used for. In certain cases, more comments are required. |
| 100 | +##Implementation Comments |
| 101 | +* In your implementation you should have comments in tricky, non-obvious, interesting, or important parts of your code. |
| 102 | +##Punctuation, Spelling and Grammar |
| 103 | +* Pay attention to punctuation, spelling, and grammar; it is easier to read well-written comments than badly written ones. |
| 104 | +##Commenting Out Code |
| 105 | +* Do not leave commented out code in the source file after testing. Proper utilization of revision control system can be relied on to retrieve any version of the code. |
| 106 | +#Other |
| 107 | +##Printing Messages in STAR |
| 108 | +* For printing messages in the STAR framework use the StMessage message manager package. |
| 109 | +##Handling Error Conditions in STAR Framework |
| 110 | +* To exit your code on an error condition in the STAR framework, return one of the STAR defined return codes from your Maker. |
| 111 | +##Exceptions to the Rules |
| 112 | + |
| 113 | +The coding conventions described above have to be followed. However, like all good rules, these sometimes have exceptions. |
| 114 | +Existing Non-Conformant Code |
| 115 | +* It is permissible to deviate from the rules when dealing with code that does not conform to this style guide. For example, in naming something that is analogous to an existing C or C++ entity then the existing naming convention scheme can be followed. |
| 116 | + |
| 117 | +#Parting Words |
| 118 | + |
| 119 | +Use common sense and BE CONSISTENT. |
| 120 | + |
| 121 | +When editing code, take a few minutes to look at the code and determine its style. |
| 122 | + |
| 123 | +The point about having style guidelines is to have a common vocabulary of coding so people can concentrate on what the programmer is saying, rather than on how he/she is saying it. Global style rules are presented here so people know the vocabulary. However, local style is also important. If the code added to a file looks drastically different from the existing code around it, the discontinuity throws readers out of their rhythm when they go to read it. Try to avoid this. |
0 commit comments