TWiki
>
ILCTPC Web
>
Software
>
MarlinTPC
>
MarlinTPCDeveloperWorkbook
>
MarlinTPCCodingRules
(revision 1) (raw view)
Edit
Attach
PDF
---+!! Checklist %TOC% In all following steps no compiler warnings shall remain with the compiler set to _all warnings on_ and _pedantic mode!_ ---++ Keep it simple! Use ANSI C++, STL, containers, standard !MarlinTPC algorithms. ---++ Revision and Parameter Logging Implement revision and parameter logging according to the [[https://twiki.cern.ch/twiki/bin/view/ILCTPC/MarlinTPCDeveloperWorkbook][MarlinTPC Developper Wiki]]. Don't forget to execute svn propset! ---++ Nesting Try to avoid deep (about three is tolerable) nesting of statements like =for, if, while, do=. It will decrease both, performance and readability. ---++ Casts Often casts can even be avoided by a sensible declaration of variables. If not, use explicit C++ casts: =dynamic_cast<type>(variable)= e.g. for converting collections to the real LCIO objects. =static_cast<type>(variable)= instead of C-type casts (e.g. =static_cast<float>(variable)= instead of =(float) variable=) =reinterpret_cast<type>= well, never encountered that one so far... ---++ STL Containers Use iterators for STL containers. *Naming:* itContent (e.g. =itPulses=) Iterators are usualy used within loops. It's convenient to generate a local object from the content of the collection iterator. That saves =dynamic_cast= statements and enhances readability. ---++ Exception Handling Perform exception handling! Think what could go wrong when issuing commands in the code and provide a controlled routine for handling these cases. If you can avoid error states by checking with =if= conditions do that. If you need to cope with error states and can't avoid them before they happen: =try ... catch= blocks are prefered for this, Marlin provides some [[http://ilcsoft.desy.de/marlin/v00-10-03/doc/html/Exceptions_8h-source.html][exceptions]] already: Don't use =assert= statements. Remember to notify the user by logging output (see [[#LoggingAnchor][Logging]]). #LoggingAnchor ---++ Logging Use =m_out(Level)= instead of =cout= and the formerly used =streamlog_out(Level)=, because severity levels can be assigned and the issuing processor is printed. ---++ Obsolete Code Fragments Check for and remove obsolete variables, functions, types, constants, =#include= statements and other unused code fragments. ---++ Constants Avoid unmotivated numbers in the code, but make them (local) constants with a meaningful name (e.g. instead of =0.78125= say =TDC_TIME_BIN_WIDTH=). *Naming:* all letters upper case, "words" connected with underscores (example: s.a.) Don't use =#define= constants. Replace them by =static const= variables. The only exception is the mandatory =#ifndef PROCESSOR_HEADER_FILE_NAME_H #define PROCESSOR_HEADER_FILE_NAME_H = 1 #endif= construction in the header file to steer the compiler. Declare public member variables always as =const=. ---++ Variables *Naming:* first word starts with lower case letter, following words start upper case (e.g. =myFancyVariableName=) *Naming of member variables in protected und private:* start with underscore, after that like non member Variables (e.g. =_myMemberVariable=) Declare variables as local as possible (Where in the code is it used?). Declare them clearly at the beginning of the corresponding code block. Check whether using a constant would be sufficient (Perhaps the variable doesn't change anyway after its initialisation?). Try to name variables as meaningful as possible, which includes to avoid abbreviations. If they are not avoidable (say for lengthy formulas) provide extensive commentary text and think of using Doxygen were !LaTeX statements are possible. Especially for boolean variables names containing "is" or "has" can be very helpfull for reading =if= conditions. *This holds for naming in general!* ---++ Type names (declared by =class, typedef, struct=) *Naming:* each word starts upper case (e.g. =FancyClass()=). If the class describes a MarlinTPC Processor include Processor at the end of the class name (e.g. =VeryComplicatedTaskSolverProcessor()=). Don't use =typedef= for renaming things, but merely to abbreviate declarations which are difficult to use or understand otherwise (e.g. nestings of STL containers, like maps of vectors and the like). But find a meaningful name! It might be more sensible to write a dedicated class with specialised access functions for such objects. ---++ Functions, Methods *Naming:* first word starts lower case, following words start upper case (e.g. myFancyFunction()) Provide Access to Membervariables of a class by Attribute functions. Attribute functions: =getValue(), setValue()=; declare retrieving functions as const: =getValue() const;= Boolean functions: =isOfColour(), hasProperty()= ---++ Documentation Document classes, member functions, parameters, member variables, types, authors in the header file with Doxygen! Document each important step in the source file. Document first of all *why* the line of code is there. Give hints for possible future developments – you might be the developper! If it is not at once clear from the code what it does, try to rewrite it in a clearer way. Only if that is not possible, explain in a comment also *what* it does. Put comments on closing brackets of larger code blocks (=#endif, for, if, else, do, while, ...=) ---++ Code Formatting Let the beautifier run over the code. So far _bcpp_ and _[[http://astyle.sourceforge.net/][astyle]]_ have been used. _Astyle_ has more settings to influence the code formatting, but doesn't influence the number of blank lines, which _bcpp_ does. Reduce multiple blank lines in header and source files with: <verbatim>cat -s file > tempfile mv tempfile file</verbatim> Go for good typography! Remove spaces in front of semicolons and commas as well as double semicolons with the "Find & Replace" function of your editor by searching for: <verbatim>" ;" --> ";" " ," --> "," ";;" --> ";"</verbatim> _repeatedly_ until nothing is left over. Of course you can also try to do all of that within a shell script. Now, conciously, format the code with blank lines: _1 blank line (where a preceding comment belongs to the block):_ * between variable declarations of different "topic" * before formulas * before code blocks * after =namespace= * before and after =public, private, protected= * between =#include= groups (have a comment here for each group, like =//Marlin, //C++, //Gear=) _3 blank lines:_ * before member functions in the source file Do spell check your comments and also your source code! Have a last good look by eye! Again: No compiler warnings shall remain (all warnings on, pedantic mode)! ---++ That's it You can test and then commit your code to the repository. -- Main.OliverSchaefer - 10 Jul 2009 * [[%ATTACHURL%/astyle.cfg][astyle.cfg]]: Astyle steering file for the MarlinTPC code layout
Attachments
Attachments
Topic attachments
I
Attachment
History
Action
Size
Date
Who
Comment
cfg
astyle.cfg
r1
manage
0.3 K
2009-07-10 - 14:26
UnknownUser
Astyle steering file for the
MarlinTPC
code layout
Edit
|
Attach
|
Watch
|
P
rint version
|
H
istory
:
r7
|
r4
<
r3
<
r2
<
r1
|
B
acklinks
|
V
iew topic
|
Raw edit
|
More topic actions...
Topic revision: r1 - 2009-07-10
-
unknown
Log In
ILCTPC
ILCTPC Web
Create New Topic
Index
Search
Changes
Notifications
Statistics
Preferences
Public webs
Public webs
ABATBEA
ACPP
ADCgroup
AEGIS
AfricaMap
AgileInfrastructure
ALICE
AliceEbyE
AliceSPD
AliceSSD
AliceTOF
AliFemto
ALPHA
Altair
ArdaGrid
ASACUSA
AthenaFCalTBAna
Atlas
AtlasLBNL
AXIALPET
CAE
CALICE
CDS
CENF
CERNSearch
CLIC
Cloud
CloudServices
CMS
Controls
CTA
CvmFS
DB
DefaultWeb
DESgroup
DPHEP
DM-LHC
DSSGroup
EGEE
EgeePtf
ELFms
EMI
ETICS
FIOgroup
FlukaTeam
Frontier
Gaudi
GeneratorServices
GuidesInfo
HardwareLabs
HCC
HEPIX
ILCBDSColl
ILCTPC
IMWG
Inspire
IPv6
IT
ItCommTeam
ITCoord
ITdeptTechForum
ITDRP
ITGT
ITSDC
LAr
LCG
LCGAAWorkbook
Leade
LHCAccess
LHCAtHome
LHCb
LHCgas
LHCONE
LHCOPN
LinuxSupport
Main
Medipix
Messaging
MPGD
NA49
NA61
NA62
NTOF
Openlab
PDBService
Persistency
PESgroup
Plugins
PSAccess
PSBUpgrade
R2Eproject
RCTF
RD42
RFCond12
RFLowLevel
ROXIE
Sandbox
SocialActivities
SPI
SRMDev
SSM
Student
SuperComputing
Support
SwfCatalogue
TMVA
TOTEM
TWiki
UNOSAT
Virtualization
VOBox
WITCH
XTCA
Cern Search
TWiki Search
Google Search
ILCTPC
All webs
Copyright &© 2008-2023 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
or Ideas, requests, problems regarding TWiki? use
Discourse
or
Send feedback