source: JEM-EUSO/esaf_lal/tags/v1_r0/esafdoc/DevelopersGuide/ClassFormat.tex @ 117

%------------------------------------------------------------------------------
\section{Classes coding conventions}
%------------------------------------------------------------------------------

%------------------------------------------------------------------------------
\subsection{Files}
%------------------------------------------------------------------------------
All files belonging to the ESAF CVS are required to have basic information stored in a standard header like the following:

\begin{displaycode}
// $Id: ClassFormat.tex 1117 2004-09-29 10:07:43Z thea $
// Author: A.Thea   2004/07/19

/*****************************************************************************
 * ESAF: Euso Simulation and Analysis Framework                              *
 *                                                                           *
 *  Id: ParamOpticalSystem                                                   *
 *  Package: Optics                                                          *
 *  Coordinator: Alessandro.Thea                                             *
 *                                                                           *
 *****************************************************************************/
\end{displaycode}

\begin{description}
\item{\verb+$Id: ClassFormat.tex 1117 2004-09-29 10:07:43Z thea $+}: CVS file informations.
\item{\verb+Author+}: the name of the creator and the creation date. It is read by the automatic documentation system.

\item{\verb+Id+}: string that identifies the file (i.e. the class name or the namespace name).
\item{\verb+Package+}: the name of the package it belongs to.
\item{\verb+Coordinator+}: the package coordinator identifier, $<FirstName>.<LastName>$.
\end{description}

The ESAF header must be present in header, source and config files (\code{.hh},\code{.cc},\code{.cfg}).


%------------------------------------------------------------------------------
\section{Comments}
%------------------------------------------------------------------------------

In a projects as big as \ESAF{}, commenting the code is essential.
Moreover, comments written in the right format can be intercepted and included them in the documentation.
In \ESAF{} we use this approach so each developer has to keep up-to-date only the code documentation and
 the automatic documentation system takes care of producing the package documentation.

For each class three different type of comments are required:
\begin{enumerate}
    \item A header inside the header file,
    \item Class and class' parameter description in the source file,
    \item Class' member functions explanation in the source file.
\end{enumerate}

%------------------------------------------------------------------------------
\subsection{Header files}
%------------------------------------------------------------------------------

A typical \ESAF{} class looks like:

\begin{displaycode}
////////////////////////////////////////////////////////////////////////////////
//                                                                            //
// ParamOpticalSystem                                                         //
//                                                                            //
// Parameterized optical system                                               //
//                                                                            //
////////////////////////////////////////////////////////////////////////////////

class ParamOpticalSystem : public OpticalSystem {
public:
    ParamOpticalSystem();
    virtual ~ParamOpticalSystem();
    
private:

    enum EPsfType { kPointLike, kGaussian };

    void Init();
    Double_t *fIntegral;         // fNbins+1 size array containing the
                                 // line integral of the fs profile
    Int_t fNbins;                // size of fIntegral

    EsafConfigClass(Optics,ParamOpticalSystem)

    ClassDef(ParamOpticalSystem,1)
};
\end{displaycode}

For each class or namespace, two comments are required: class/namespace title before its declaration, and class data members description. 

%------------------------------------------------------------------------------
\subsubsection{Class title}
%------------------------------------------------------------------------------

Just before the class declaration there is a brief description of the class (few words).
In case of a single class header may be redundant but becomes useful when several classes are defined in the same file.

\begin{displaycode}
////////////////////////////////////////////////////////////////////////////////
//                                                                            //
// ParamOpticalSystem                                                         //
//                                                                            //
// Parameterized optical system                                               //
//                                                                            //
////////////////////////////////////////////////////////////////////////////////
\end{displaycode}

%------------------------------------------------------------------------------
\subsubsection{Data members}
%------------------------------------------------------------------------------

The descriptions must follow data member declaration, inline or in the following line.

Sometime special keywords can be found after \verb+//+. These information are used by the dictionary generator \path{rootcint} Special comments (\code{ClassVersionID != 0})%(\ref{Automatic Generated Streamers, ROOT UG, pag 202})
like \code{EShower}, \code{EAtmosphere} and \code{EDetector}.

\begin{displaycode}
Double_t *fIntegral;         
// fNbins+1 size array containing line integral of the fs profile

Int_t fNbins;                // size of fIntegral
\end{displaycode}

%------------------------------------------------------------------------------
\subsection{Source files}
%------------------------------------------------------------------------------

\subsubsection{Class Documentation}
The information stored in the class documentation block is twofold. First, features and proposes are explained in detail.
Then, if class uses \ESAF{} configuration system, the list of the config file parameters follows.

\begin{displaycode}
//_____________________________________________________________________________
//   Parameterized Optical System
//   ===========================
//
//   Parameterized optical system. This Optical System is done to reproduce the
//   behaviour of an optics design through a set of parameters.
//   The main pourpose is to simulate and OS with a given Triggering efficacy
//   without the need of the full MC simulation.
//
//   ParamOpticalSystem behaves as an ideal optical system with a given focal
//   surface.
//
//   The position an incoming photon hits the focal surface is calculated
//   accordingly the relation
//
//   d = (Dmax/ThetaMax)*theta
//
//   where:
//   d is the distance of the impact point on the FS from the center of the FS
//   calculated along the FS.
//
//   Dmax is the maximum distancs.
//
//   theta is the angle between the incoming photon direction and the optical
//   axis.
//
//   ThetaMax is the maximum value of theta accepted by the optics.
//
//   Config file parameters:
//   =======================
//
//   fPos.Z [mm] : Z coordinate of the bottom base of the OpticalSystem in
//   Detector reference System.
// 
//   fPsfType [option]: type of PSF to use.
//   - options
//        point: No spread. 
//        gauss: Gaussian psf. RMS and angles of incidence listed in
//               fGaussSpread.filename
//
\end{displaycode}

Note that EVERYTHING until the first non-commented line is considered as a valid class description block.


Parameters can be numbers or strings.
Unit of measure must be specified when the parameter is not pure numbers, otherwise the  \code{[string]} keyword, in case of strings.

In the latter case all the valid options must be listed after the parameter description.

%------------------------------------------------------------------------------
\subsubsection{Member fuctions}
%------------------------------------------------------------------------------
 A member function description block starts immediately after '\verb+{+' and looks like this:

\begin{displaycode}
//______________________________________________________________________________
Double_t ParamOpticalSystem::FocalSurfProfile( Double_t r ) const {
    //
    // Profile of the focal surface Z(r)
    //

    if ( r < 0 || r > fRmax ) return 0;

    return fFocalSurfShape->Eval(r);
}
\end{displaycode}

Like in a class description block, EVERYTHING until the first non-commented line is considered as a valid member function description block.