(r1) MarlinTPCCodingRules < ILCTPC

ILCTPC Web>Software>MarlinTPC>MarlinTPCDeveloperWorkbook>MarlinTPCCodingRules (revision 1) (raw view)~~EditAttachPDF~~
---+!! 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&lt;type&gt;(variable)= e.g. for converting collections to the real LCIO objects.

=static_cast&lt;type&gt;(variable)= instead of C-type casts (e.g. =static_cast&lt;float&gt;(variable)= instead of =(float) variable=)

=reinterpret_cast&lt;type&gt;= 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 &ndash; 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
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
Topic revision: r1 - 2009-07-10 - unknown
ILCTPC
Public webs
- 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