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

Last change on this file was 1208, checked in by garnier, 16 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.