Documentation/CodingRules/CodingAndStyleRules.tex - master - githubmirror/cmssw

Documentation/CodingRules/CodingAndStyleRules.tex
234 строки9 KB
Giulio Eulisse
Snapshot of CMSSW_6_2_0_pre8.
26 июн 2013, 18:12
26 июн 2013, 18:12214ab73
\documentclass{cmspaper}
 
\begin{document}

\begin{titlepage}

\internalnote{2005/000}
\date{26 July 2005}

\title{CMS Naming, Coding And Style Rules}

\begin{Authlist}
The CMS Offline Software Developers
\end{Authlist}

\begin{abstract}

This document describes the naming, coding and style rules, as well as
design, coding and style recommendations for CMS software
written in C++. 
All code submitted for a CMSSW release is automatically checked for
compliance. 
While recommendations cannot be enforced for practical reasons, CMS
code developers are strongly encouraged to adhere to them. Cases
where the recommendations cannot be followed should be justified and
documented.
   
\end{abstract} 

\end{titlepage}

\setcounter{page}{2}

\section{Introduction}

This document describes the CMS C++ software naming, coding, style and 
documentation rules and recommendations.

All CMS C++ software is expected to comply with the rules. The asterisk (*) 
after some rules indicates that there may be exceptional use cases where 
the rule may be violated with good justification.

Coding rules are meant to prevent serious problems in what concerns software 
function and performance, maintainability, usability and portability.
They are enforced by the adopted code checking tool.

The rule-checker may be configured and run by individual developers, 
as well as in prerelease context, without causing build failures or 
inordinate amounts of rule violation reports.

The rule-checker may be configured and run for public releases in such a 
way that a violation of a mandatory rule causes a build failure, provided 
that the developer responsible may do one of the following three things:
	
\begin{enumerate}	
\item Modify the code to avoid the violation (the normal response)
\item If the code does not violate the rule, and the developer believes 
the report is due to a bug in the implementation of the rule checking, 
the bug should be reported in Savannah and also to the release 
administrator(s) and tool experts.  If they agree that it is a bug, 
they temporarily disable the rule entirely or make it optional.  
When the bug is fixed, the rule is re-enabled.
\item If the code does violate the rule, but the developer feels that 
the code should violate the rule because the rule is fundamentally flawed, 
the developer must request that the rule be modified or made optional. 
A group of 2 or 3 experts handle these requests.
\end{enumerate}

In addition to the rules described here, ANSI-standard C++ compliance is to be
enforced by the compiler. 

Guidelines and to some extent naming and style rules (where exceptions are to 
be decided on a case-by-case basis, justified and documented) cannot always 
be enforced. Every effort shall be made to provide automated checking so as to
help developers improve code as desired.


\section{CMS Naming Rules}

\begin{enumerate}

\item C++ header files use the suffix .h e.g. CaloCluster.h
\item C++ source files use the suffix .cc e.g. CaloCluster.cc
\item Name header files after the class.
\item Name source files after the class.
\item For class, struct, type and enumeration names use upper class initials 
e.g. GeometryBuilder. 
\item For namespaces use lower case e.g. namespace edm.
\item Start method names with lower case, use upper case initials for
  following words e.g. collisionPoint() (allowed exception: implementation of
  virtual methods inherited from external packages e.g. ProcessHits()
  method required by Geant4).
\item Start data member names with lower case; use ``the'' or ``m\_'' or a
  trailing ``\_'' to distinguish data member from getter method
  e.g. theMomentum or m\_momentum or momentum\_.
\item Do not use single character names, except for loop indices.
\item Do not use special characters, except for ``\_'' where allowed.
\item Do not use ``\_'' as first character.
\item Do not use ``\_\_''.
\end{enumerate}

\section{CMS Coding Rules}

\begin{enumerate}

\item Protect each header file from multiple inclusion with
\begin{verbatim}
#ifndef PackageName_FileName_h
#define PackageName_FileName_h
(body of header file)
#endif
\end{verbatim}
\item Each header file contains one class declaration only. (*)
\item Header files must not contain any implementation except for
  class templates and code to be inlined.
\item Do not inline virtual functions.
\item Do not inline functions which contain control structures which require block scoping.
\item Classes must not have public data members.
\item In your own packages, use forward declarations if they are sufficient. 
\item Do not forward declare an entity from another package.
\item Do not use absolute directory names or relative file paths in \#include directives.
\item Do not use global data. Encapsulate them in an instance of a class.
\item Use global functions only for symmetric binary operators. (*) 
\item Use ``0'' not ``NULL''.
\item Use types like int, long, size\_t, ptr\_diff consistently and
  without mixing them (important for 64-bit architectures).
\item Use the bool type for booleans.
\item Define constants using enum or const, never \#define or magic
  numbers.
\item Use new and delete instead of malloc, calloc, realloc and free.
\item Have assignment operators return a reference to *this.
\item If you have an assignment operator, have a copy constructor and
  vice versa.
\item Do not use goto.
\item Make ``const'' all methods that do not need to be non-const.
\item Do not use function-like macros.
\item Use C++ casts, not C-style casting.
\item Do not use the ellipsis notation for function arguments. (*)
\item Do not use union types. (*)
\item If a class has at least one virtual method, it must have a
  public virtual destructor or (exceptionally) a protected destructor.
\item Always redeclare virtual functions as virtual in derived
  classes.
\item Do not use functions that manipulate UNIX file descriptors and FILE objects directly 
      to produce output. Examples: printf, fprintf, scanf, fscanf. 
\item Pass by value arguments which are not to be modified and are
  built-in types or small objects, otherwise pass arguments of class
  types by reference or, if necessary, by pointer. 
\item Declare a pointer or reference argument passed to a function as
  const if the function does not change the object bound to it. 
\item The argument to a copy constructor and to an assignment operator
  must be a const reference.  (*)
\item Do not let const member functions change the state of the object. 
\item A function must never return or in any way give access to
  references or pointers to local variables (stack variables) outside 
  the scope in which they are declared. 
\item The public, protected and private sections of a class must be
  declared in that order. 
\item Keep the ordering of methods in the header file and in the
  source file identical. 
\item Provide argument names in method declarations in header file to indicate
  usage.
\item Statements should not exceed 100 \em{(we may adjust this limit)}
  characters (excluding leading spaces). 
\item Limit line length to 120 \em{(we may adjust this limit)}
  character positions (including white space and expanded tabs). 
\item Data members of a class must not be redefined in derived classes. 

\end{enumerate}

\section{CMS Style Rules}

\begin{enumerate}

\item Do not indent pre-processor directives with the code.
\item Never change the language syntax using \#define.
\item Do not use spaces between method names and their argument list
  e.g. foo() rather than foo ().
\item Do not use spaces in front of \([]\), () and on either side of 
  \(\rightarrow\). 
\item Separate expressions in a ``for'' statement by spaces.
\item Use the same indentation for comments as for the block the comments refer to.

\end{enumerate}

\section{CMS Documentation Rules}

\begin{enumerate}

\item Use Doxygen-style comments.
\item Each class contains a Doxygen-style description of the class
  functionality placed at the beginning of the header file.

\end{enumerate}

\section{Design and Coding Guidelines}

\begin{enumerate}

\item Avoid inlining unless you are sure you have a relevant performance problem.
\item Use either ``set'' or function overloading for setters e.g. setMomentum(double m) 
      or momentum(double m) but be consistent in your choice of scheme.
\item Use either ``get'' or function overloading for getters e.g. getMomentum() or momentum()
      but be consistent in your choice of scheme.
\item Make sure each header file parses by itself.
\item Use string, not char *.
\item Do not use arrays, use STL containers.
\item Define and use proper granularity exception types. 
\item Do not use exception specifications.
\item Do not use the singleton pattern; use framework services.
\item Use the observer pattern to dispatch only const for
  non-intrusive monitoring or validation.
\item Use namespaces to group collaborating classes that provide a
  certain functionality e.g. edm or mantis. 
\item Do not use namespaces to group detector system classes
  e.g. tracker, calo etc.
\item Encapsulate algorithms in namespaces.

\end{enumerate}

\begin{thebibliography}{5}
  \bibitem {NOTE000} {\bf CMS Note 1998/071},
    J.P. Wellisch,
    {\em "CMS Coding Rules"}.
  \bibitem {NOTE001} {\bf CMS Note 1998/072},
    J.P. Wellisch,
    {\em "CMS Style Rules"}.
  \bibitem {NOTE002} {\bf RuleChecker set for ALICE}.
  \bibitem {NOTE003} {\bf RuleChecker set for ATLAS}.
  \bibitem {NOTE004} {\bf RuleChecker set for LHCb}.

\end{thebibliography}
 
\end{document}