source: trunk/documents/UserDoc/UsersGuides/SoftwareReferenceManual/html/CodeConvention/codeConvention.html @ 1219

Last change on this file since 1219 was 1208, checked in by garnier, 15 years ago

CVS update
File size: 10.7 KB
Line 
1<HTML>
2<TITLE>
3</TITLE>
4<!-- Changed by: Katsuya Amako,  2-Dec-1998 -->
5
6<BODY>
7<TABLE WIDTH="100%"><TR>
8<TD>
9</TD>
10
11<TD ALIGN="Right">
12</TD>
13</TR></TABLE>
14<P>
15
16<BR><BR>
17<P ALIGN="Center">
18<FONT SIZE="+4" COLOR="#238E23">
19<B>2. Code Convention</B>
20</FONT>
21<BR><BR>
22
23<HR ALIGN="Center" SIZE="7%">
24<BR><BR>
25
26
27<!-- ============================================== Section --> 
28"A major benefit of object-oriented programming languages like
29 C++ is the degree of reuse that can be achieved in
30 well-engineered systems. A high degree of reuse means that
31 far less code must be written for each new application;
32 consequently, that is far less code to maintain." (G.Booch).
33<P>
34The set of rules listed here are the only 'imposed' rules which have
35been adopted for the development of Geant4. We think they might become
36useful also for those users who will develope C++ code for applications
37related to Geant4 and, why not?, in general !
38<P>
39
40<H2>2.1 Introduction</H2>
41
42Geant4 as object-oriented toolkit is thought to be an integration of
43components (sets of classes) which are specific to the HEP applications
44or part of general foundation class libraries, math libraries
45(commercial or free) already implemented and distributed world-wide,
46useful as building blocks for a wide variety of applications. Even
47within HEP, the reusability of object-oriented software across
48different laboratories and between different experiments will be
49essential.
50<P>
51As an object-oriented toolkit, Geant4 can be certainly extended and
52refined by physicists and experts all over the world, who may have used
53or will use their own coding conventions and rules, different from each
54others.
55It is and has been then important not to impose too fixed rules or
56style-conventions for a world-wide collaboration like GEANT4, but just
57flexible and adequate guidelines for programming and coding styles.
58<P>
59"C++ was designed to support data abstraction and object-oriented
60 programming in addition to traditional C programming techniques.
61 It was not meant to force any particular programming style upon
62 all users" (B.Stroustrup).
63<P>
64
65<HR>
66<H2>2.2 Programming guidelines</H2>
67
68The programming guidelines are the ones which refer to the way of using
69the features of the programming languages. They have to do with things
70like the adhesion to the object oriented paradigm (data-hiding,
71encapsulation, etc ...), the performance and portability.
72<P>
73
74<UL>
75<LI>Every class should have at least one constructor and a
76    destructor even if it does nothing or is defined to do nothing.
77    <P>
78    If a class does not have a constructor there is no guarantee of
79    how objects of that class will be initialized, whilst data
80    members should be explicitly initialized therein. When the
81    constructor dynamically allocates memory, a destructor must be
82    added to return the memory to the free pool when an object gets
83    cleaned up.
84<P>
85<LI>Each class should have an assignment operator:<BR> 
86    <KBD>ClassName& operator=(const ClassName&)</KBD><BR>
87    and a copy constructor:<BR> 
88    <KBD>ClassName(const ClassName&)</KBD><BR>
89    when allocating subsidiary data structures on the heap or
90    consume any other kind of shared resources.
91    <P> 
92    The assignment operator is called when one instance of a class
93    is assigned to another.
94    The copy constructor defines the behaviour of the class when it
95    is passed by value as an argument, returned by value from a
96    function, or used to initialize one instance with the value of
97    another class instance. Defining this constructor, all the class
98    objects are copied properly. When it doesn't make sense to copy
99    or assign instances of a given class, the copy constructor or
100    the = operator should be made private.
101<P>
102<LI>Data members should be made private/protected and accessed by
103    inline functions in order to best implement information-hiding.
104    <P>
105    Inline expansion avoids the overhead of a function call and can
106    result in large savings of CPU time expecially if applied to
107    member functions supporting public access to private data
108    (allowing the maximum data-hiding for a required performance).
109<P>
110<LI>The use of global variables or functions should be avoided where
111    possible, in order to respect encapsulation.
112<P>
113<LI>The use of friend classes should be avoided where possible.
114    <P>
115    To garantee the encapsulation of a base class is always
116    preferable to use protected data over friends or public data
117    and then use inheritance.
118<P>
119<LI>The use of type casting should be avoided.
120    <P>
121    Especially from <KBD>const*</KBD> or <KBD>const</KBD>, type
122    casting may be dangerous
123    for data-hiding. In addition pointers should not be cast to int
124    for portability reasons.
125<P>
126<LI>Hard-coded numbers within the code must be avoided.
127    <P>
128    For portability and maintainability reasons. The use of costants
129    (<KBD>const</KBD>) is a valid solution.
130<P>
131<LI>Instead of the raw C types, the G4 types should be used.
132    <P>
133    For the basic numeric types (int, float, double, etc ...),
134    different compilers and different platforms provide different
135    value ranges. In order to assure portability, the use of G4int,
136    G4float, G4double, which are base classes globally defined is
137    preferable. G4 types implement the right generic type for a
138    given architecture.
139</UL>
140<P>
141
142<HR>
143<H2>2.3 Coding-style conventions</H2>
144
145The coding-style guidelines are the ones which refer to the editing
146styles of the source code. They have to do with things like the code
147maintainability and readability.
148<P>
149
150<UL>
151<LI>The public, protected and private keywords must be used
152    explicitly in the class declaration in order to make easier
153    code readability.
154<P>
155<LI>English and self-explaining names for constants, variables and
156    functions should be used for code readability.
157    <P>
158    Possibly avoid the use of underscore "_" characters within
159    variables or function names (ex. <KBD>theTotalEnergy,
160    SetEnergyTable(), GetTrackPosition()</KBD>, ...).
161<P>
162<LI>The code must be properly indented (ex. 2 characters indentation
163    when inside a control structure) for readability reasons.
164<P>
165<LI>Each GEANT4 class name should begin with G4
166    <P>
167    (ex. <KBD>G4Material, G4GeometryManager, G4ProcessVector</KBD>, ...)
168    to  keep an homogeneous naming style for GEANT4 specific classes.
169<P>
170<LI>Each header file should contain only one or related class
171    declarations.
172    <P>
173    For maintainability reasons and to make easier retrieval of
174    classes' definitions across each category.
175<P>
176<LI>Each class implementation source code should go into a single
177    source file.
178    <P>
179    For maintainability reasons and to make easier retrieval of
180    classes' implementations across each category.
181<P>
182<LI>Each header file must be protected from multiple inclusions.
183    <P>
184    In order to avoid multiple declarations and circular dependences
185    in the code. Ex.:
186    <PRE>
187    #ifndef NAME_HH
188    #define NAME_HH
189    ...
190    #endif
191    </PRE>
192
193<LI>Each file should contain a short header about the author,
194   updates (CVS) and date.
195   <P>
196   All files should begin with:<BR>
197   <KBD> // $Id: codeConvention.html,v 1.2 1998/12/02 03:50:59 amako Exp $</KBD>
198   and a half line comment with the name of the original author,
199   update notes and dates. The <KBD>$Id: codeConvention.html,v 1.2 1998/12/02 03:50:59 amako Exp $</KBD> will expand to filename
200    and  last updater in CVS.
201</UL>
202<P>
203
204<HR>
205<H2>2.4 Coding-style for writing a Geant4 application </H2>
206<UL>
207<I> Style to adopt to write a Geant4 main application.</I>
208</UL>
209
210<HR>
211<H2>2.5 Programming Suggestions learned from experience</H2>
212
213Here is a list of rules/hints which we could collect after all
214periodical sessions of QA/QC on the developed code. These "hints" have
215been made public to Geant4 developers in order to avoid the most common
216mistakes and improve the quality of the code.
217<P>
218
219<UL>
220<LI>Initialize all data members of a class in each constructor
221    (pointers, <KBD>G4ints</KBD>, etc.)
222    <P>
223    Bugs related to this problem are extremely difficult to track
224    down !
225<P> 
226<LI>Do not insert items allocated on the heap into value-based
227    collections (Or, at least, preserve the pointer for deletion)
228<P>
229<LI>Properly destruct objects
230    <P>
231    In particular, remember to delete items of a pointer based
232    collection which were allocated on the heap.
233<P>   
234<LI>Inline short and frequently used member functions
235    <P>
236    Define inlined functions in the .icc file and check that the
237    compiler is effectively inlining them (using the proper
238    compiler options).
239<P>
240<LI>A member function doing allocations on the heap may leak memory
241    if the user invokes the function several times
242    <P>
243    Check if allocation was done already.
244<P>
245<LI>Access of elements of the RWTPtrOrderedVector collections
246    <P>
247    As of Tools.h++ V7.0.1: <BR>
248    <KBD>operator()</KBD> fetches an element and does no bounds
249    checking of the index.<BR> 
250    <KBD>operator[]</KBD> fetches an element and does bounds check.
251    The library is only aware of insertions by <KBD>insert()</KBD> 
252    (and related functions).
253    Therefore:
254    <UL>   
255    <LI>filling the array by insert() and reading it with [] works;
256    <LI>filling the array by () and reading it by () works;
257    <LI>filling by [] does NOT work any more.
258    </UL>
259<P>
260<LI>The return type of function main()
261    <P>
262    use the declaration int <KBD>main()</KBD> instead of
263    <KBD>void main()</KBD> or <KBD>main()</KBD>
264    (this "implicite int" will be excluded from the C++ standard
265    soon).
266<P>
267<LI>Programs should return: <BR>
268    <UL>
269    <LI>0 or <KBD>EXIT_SUCCESS</KBD> on success;
270    <LI>nonzero or <KBD>EXIT_FAILURE</KBD> on error.
271    </UL>
272<P>
273<LI>Deletion of elements in pointer based collections
274    <P>
275    Items stored in pointer collections e.g. <KBD>RWTPtrOrderedVector</KBD>
276    can be deleted by the method <KBD>clearAndDestroy()</KBD>.
277<P>
278<LI>Problems with classes that cannot be copied/assigned
279    to/constructed etc.
280    <P>
281    It is best to make the corresponding member functions private.
282<P>
283<LI>Use const declarations whenever possible instead of numbers
284    in the code
285<P>
286<LI>Avoid multiple return points in a method where possible
287    <P>
288    Methods with multiple return points cannot be inlined and
289    some compilers (e.g. HP-CC) complain about this.
290<P>
291<LI>Use G4Exception to print an error message and exit the program
292<P> 
293<LI>Use costants and units defined in <KBD>PhysicalConstants.h</KBD> and
294    <KBD>SystemOfUnits.h</KBD>
295    <P>
296    Look inside those files in CLHEP/Units before defining local
297    constants or putting hard-coded numbers in the code.
298<P>
299<LI>Do not code bit-wise operations within a word. Consider
300    a word as atomic!
301</UL>
302
303
304<BR><BR>
305
306</BODY>
307</HTML>
308
309
310
311
312
313
314
315
Note: See TracBrowser for help on using the repository browser.