Increment OCCT version up to 7.4.0
[occt.git] / dox / dev_guides / contribution / coding_rules.md
1 Coding Rules {#occt_dev_guides__coding_rules}
2 ======================================
3
4 @tableofcontents
5
6 @section occt_coding_rules_1 Introduction
7
8 The purpose of this document is to define a common programming style for Open CASCADE Technology.
9
10 The common style facilitates understanding and maintaining a code developed cooperatively by several programmers. In addition, it enables construction of tools that incorporate knowledge of these standards to help in the programming.
11
12 OCCT programming style follows common and appropriate best practices, so some guidelines have been excerpted from the public domain.
13
14 The guide can be improved in the future as new ideas and enhancements are added.
15
16 @subsection occt_coding_rules_1_1 Scope of the document
17
18 Rules in this document refer to C++ code. However, with minor exceptions due to language restrictions, they are applicable to any sources in Open CASCADE Technology framework, including:
19 - C/C++
20 - GLSL programs
21 - OpenCL kernels
22 - TCL scripts and test cases
23
24 @section occt_coding_rules_2 Naming Conventions
25
26 @subsection occt_coding_rules_2_1 General naming rules
27
28 The names considered in this section mainly refer to the interface of Open CASCADE Technology libraries or source code itself.
29
30 ### International language [MANDATORY]
31
32 Open CASCADE Technology is an open source platform available for an international community, thus all names need to be composed of English words or their abbreviations.
33
34 ### Meaningful names
35
36 Names should be meaningful or, at least, contain a meaningful part. To better understand this requirement, let us examine the existing names of toolkits, packages, classes and methods:
37 - Packages containing words *Geom* or *Geom2d* in their names are related to geometrical data and operations.
38 - Packages containing words *TopoDS* or *BRep* in their names are related to topological data and operations.
39 - Packages ending with <i>...Test</i> define Draw Harness plugins.
40 - Methods starting with *Get...* and *Set...* are usually responsible for correspondingly retrieving and storing data.
41
42 ### Related names
43
44 Names related to a logically connected functionality should have the same prefix (start with the same letters) or, at least, have any other common part.
45 For example, method *GetCoord* returns a triple of real values and is defined for directions, vectors and points. The logical connection is obvious.
46
47 ### Camel Case style
48 Camel Case style is preferred for names.
49 For example:
50
51 ~~~~~{.cpp}
52 Standard_Integer awidthofbox;  // this is bad
53 Standard_Integer width_of_box; // this is bad
54 Standard_Integer aWidthOfBox;  // this is OK
55 ~~~~~
56
57 @subsection occt_coding_rules_2_2 Names of development units
58
59 Usually a unit (e.g. a package) is a set of classes, methods, enumerations or any other sources implementing a common functionality, which is self-contained and independent from other parts of the library.
60
61 ### No underscores in unit names [MANDATORY]
62
63 Names of units should not contain underscores, unless the use of underscores is allowed explicitly.
64
65 ### File name extensions [MANDATORY]
66
67 The following extensions should be used for source files, depending on their type:
68
69 * <i>.cxx</i> -- C++ source files
70 * <i>.hxx</i> -- C++ header files
71 * <i>.lxx</i> -- additional headers containing definitions of inline methods and auxiliary code
72
73 Note that .lxx files should be avoided in most cases - inline method should be placed in header file instead.
74
75 ### Prefix for toolkit names [MANDATORY]
76
77 Toolkit names are prefixed by *TK*, followed by a meaningful part of the name explaining the domain of functionality covered by the toolkit (e.g. *TKOpenGl*).
78
79 ### Names of public types
80
81 Names of public classes and other types (structures, enums, typedefs) should match the common pattern: name of the package followed by underscore and suffix (the own name of the type):
82
83 ~~~~~
84     <package-name>_<class-name>
85 ~~~~~
86
87 Static methods related to the whole package are defined in the class with the same name as package (without suffix).
88
89 Each type should be defined in its own header file with the name of the type and extension ".hxx".
90 Implementation should be placed in the file with the same name and extension ".cxx"; for large classes it is possible to split implementation into multiple source files with additional suffixes in the names (usually numerical, e.g. *BSplCLib_1.cxx*).
91
92 For example, class *Adaptor2d_Curve2d* belongs to the package *Adaptor2d*; it is defined in header file *Adaptor2d_Curve2d.hxx* and implemented in source file *Adaptor2d_Curve2d.cxx*.
93
94 This rule also applies to complex types constructed by instantiation of templates.
95 Such types should be given own names using *typedef* statement, located in same-named header file.
96
97 For example, see definition in the file *TColStd_IndexedDataMapOfStringString.hxx*:
98 ~~~~~
99 typedef NCollection_IndexedDataMap<TCollection_AsciiString,TCollection_AsciiString,TCollection_AsciiString> TColStd_IndexedDataMapOfStringString;
100 ~~~~~
101
102 ### Names of functions
103
104 The term **function** here is defined as:
105 - Any class method
106 - Any package method
107 - Any non-member procedure or function
108
109 It is preferred to start names of public methods from an upper case character and to start names of protected and private methods from a lower case character.
110
111
112 ~~~~~{.cpp}
113 class MyPackage_MyClass
114 {
115
116 public:
117
118   Standard_Integer Value() const;
119   void             SetValue (const Standard_Integer theValue);
120
121 private:
122
123   void setIntegerValue (const Standard_Integer theValue);
124
125 };
126 ~~~~~
127
128 @subsection occt_coding_rules_2_3 Names of variables
129
130 There are several rules that describe currently accepted practices for naming variables.
131
132 ### Naming of variables
133
134 Name of a variable should not conflict with the existing or possible global names (for packages, macros, functions, global variables, etc.).
135
136 The name of a variable should not start with an underscore.
137
138 See the following examples:
139
140 ~~~~~{.cpp}
141 Standard_Integer Elapsed_Time = 0; // this is bad - possible class   name
142 Standard_Integer gp = 0;           // this is bad - existing package name
143 Standard_Integer aGp = 0;          // this is OK
144 Standard_Integer _KERNEL = 0;      // this is bad
145 Standard_Integer THE_KERNEL = 0;   // this is OK
146 ~~~~~
147
148 ### Names of function parameters
149
150 The name of a function (procedure, class method) parameter should start with prefix *the* followed by the meaningful part of the name starting with a capital letter.
151
152 See the following examples:
153
154 ~~~~~{.cpp}
155 void Package_MyClass::MyFunction (const gp_Pnt& p);        // this is bad
156 void Package_MyClass::MyFunction (const gp_Pnt& theP);     // this is OK
157 void Package_MyClass::MyFunction (const gp_Pnt& thePoint); // this is preferred
158 ~~~~~
159
160 ### Names of class member variables
161
162 The name of a class member variable should start with prefix *my* followed by the meaningful of the name starting with a capital letter.
163
164 See the following examples:
165
166 ~~~~~{.cpp}
167 Standard_Integer counter;   // This is bad
168 Standard_Integer myC;       // This is OK
169 Standard_Integer myCounter; // This is preferred
170 ~~~~~
171
172 ### Names of global variables
173
174 It is strongly recommended to avoid defining any global variables.
175 However, as soon as a global variable is necessary, its name should be prefixed by the name of a class or a package where it is defined followed with <i>_my</i>.
176
177 See the following examples:
178
179 ~~~~~{.cpp}
180 Standard_Integer MyPackage_myGlobalVariable = 0;
181 Standard_Integer MyPackage_MyClass_myGlobalVariable = 0;
182 ~~~~~
183
184 Static constants within the file should be written in upper-case and begin with prefix *THE_*:
185 ~~~~~{.cpp}
186 namespace
187 {
188   static const Standard_Real THE_CONSTANT_COEF = 3.14;
189 };
190 ~~~~~
191
192 ### Names of local variables
193
194 The name of a local variable should be distinguishable from the name of a function parameter, a class member variable and a global variable.
195
196 It is preferred to prefix local variable names with *a* and *an* (or *is*, *to* and *has* for Boolean variables).
197
198 See the following example:
199
200 ~~~~~{.cpp}
201 Standard_Integer theI;    // this is bad
202 Standard_Integer i;       // this is bad
203 Standard_Integer index;   // this is bad
204 Standard_Integer anIndex; // this is OK
205 ~~~~~
206
207 ### Avoid dummy names
208 Avoid dummy names, such as <i>i, j, k</i>. Such names are meaningless and easy to mix up.
209
210 The code becomes more and more complicated when such dummy names are used there multiple times with different meanings, or in cycles with different iteration ranges, etc.
211
212 See the following examples for preferred style:
213
214 ~~~~~{.cpp}
215 void Average (const Standard_Real** theArray,
216               Standard_Integer      theRowsNb,
217               Standard_Integer      theRowLen,
218               Standard_Real&        theResult)
219 {
220   theResult = 0.0;
221   for (Standard_Integer aRow = 0; aRow < aRowsNb; ++aRow)
222   {
223     for (Standard_Integer aCol = 0; aCol < aRowLen; ++aCol)
224     {
225       theResult += theArray[aRow][aCol];
226     }
227     theResult /= Standard_Real(aRowsNb * aRowLen);
228   }
229 }
230 ~~~~~
231
232 @section occt_coding_rules_3 Formatting rules
233
234 To improve the open source readability and, consequently, maintainability, the following set of rules is applied.
235
236 ### International language [MANDATORY]
237
238 All comments in all sources must be in English.
239
240 ### Line length
241
242 Try to stay within the limit of 120 characters per line in all sources.
243
244 ### C++ style comments
245
246 Prefer C++ style comments in C++ sources.
247
248 ### Commenting out unused code
249
250 Delete unused code instead of commenting it or using \#define.
251
252 ### Indentation in sources [MANDATORY]
253
254 Indentation in all sources should be set to two space characters.
255 Use of tabulation characters for indentation is disallowed.
256
257 ### Separating spaces
258
259 Punctuation rules follow the rules of the English language.
260 * C/C++ reserved words, commas, colons and semicolons should be followed by a space character if they are not at the end of a line.
261 * There should be no space characters after '(' and before ')'. Closing and opening brackets should be separated by a space character.
262 * For better readability it is also recommended to surround conventional operators by a space character. 
263 Examples:
264
265 ~~~~~{.cpp}
266 while (true)                            // NOT: while( true ) ...
267 {
268   DoSomething (theA, theB, theC, theD); // NOT: DoSomething(theA,theB,theC,theD);
269 }
270 for (anIter = 0; anIter < 10; ++anIter) // NOT: for (anIter=0;anIter<10;++anIter){
271 {
272   theA = (theB + theC) * theD;          // NOT: theA=(theB+theC)*theD
273 }
274 ~~~~~
275
276 ### Declaration of pointers and references
277
278 In declarations of simple pointers and references put asterisk (*) or ampersand (&) right after the type without extra space.
279
280 Since declaration of several variables with mixed pointer types contrudicts this rule, it should be avoided. Instead, declare each variable independently with fully qualified type.
281
282 Examples:
283
284 ~~~~~{.cpp}
285 Standard_Integer   *theVariable;      // not recommended
286 Standard_Integer *  theVariable;      // not recommended
287 Standard_Integer*   theVariable;      // this is OK
288
289 Standard_Integer  *&theVariable;      // not recommended
290 Standard_Integer *& theVariable;      // not recommended
291 Standard_Integer*&  theVariable;      // this is OK
292
293 Standard_Integer  **theVariable;      // not recommended
294 Standard_Integer ** theVariable;      // not recommended
295 Standard_Integer**  theVariable;      // this is OK
296
297 Standard_Integer *theA, theB, **theC; // not recommended (declare each variable independently)
298 ~~~~~
299
300 ### Separate logical blocks
301
302 Separate logical blocks of code with one blank line and comments.
303
304 See the following example:
305
306 ~~~~~{.cpp}
307 // check arguments
308 Standard_Integer anArgsNb = argCount();
309 if (anArgsNb < 3 || isSmthInvalid)
310 {
311   return THE_ARG_INVALID;
312 }
313
314 // read and check header
315 ...
316 ...
317
318 // do our job
319 ...
320 ...
321 ~~~~~
322
323 Notice that multiple blank lines should be avoided.
324
325 ### Separate function bodies [MANDATORY]
326
327 Use function descriptive blocks to separate function bodies from each other.
328 Each descriptive block should contain at least a function name and purpose description.
329
330 See the following example:
331
332 ~~~~~{.cpp}
333 // =======================================================================
334 // function : TellMeSmthGood
335 // purpose  : Gives me good news
336 // =======================================================================
337 void TellMeSmthGood()
338 {
339   ...
340 }
341
342 // =======================================================================
343 // function : TellMeSmthBad
344 // purpose  : Gives me bad news
345 // =======================================================================
346 void TellMeSmthBad()
347 {
348   ...
349 }
350 ~~~~~
351
352 ### Block layout [MANDATORY]
353 Figure brackets <i>{ }</i> and each operator <i>(for, if, else, try, catch)</i> should be written on a dedicated line.
354
355 In general, the layout should be as follows:
356
357 ~~~~~{.cpp}
358 while (expression)
359 {
360   ...
361 }
362 ~~~~~
363
364 Entering a block increases and leaving a block decreases the indentation by one tabulation.
365
366 ### Single-line operators
367
368 Single-line conditional operators <i>(if, while, for,</i> etc.) can be written without brackets on the following line.
369
370 ~~~~~{.cpp}
371 if (!myIsInit) return Standard_False; // bad
372
373 if (thePtr == NULL)                   // OK
374   return Standard_False;
375
376 if (!theAlgo.IsNull())                // preferred
377 {
378   DoSomething();
379 }
380 ~~~~~
381
382 Having all code in the same line is less convenient for debugging.
383
384 ### Comparison expressions with constants
385
386 In comparisons, put the variable (in the current context) on the left side and constant on the right side of expression.
387 That is, the so called "Yoda style" is to be avoided.
388
389 ~~~~~{.cpp}
390 if (NULL != thePointer)    // Yoda style, not recommended
391 if (thePointer != NULL)    // OK
392
393 if (34 < anIter)           // Yoda style, not recommended
394 if (anIter > 34)           // OK
395
396 if (theNbValues >= anIter) // bad style (constant function argument vs. local variable)
397 if (anIter <= theNbValues) // OK
398
399 if (THE_LIMIT == theValue) // bad style (global constant vs. variable)
400 if (theValue == THE_LIMIT) // OK
401 ~~~~~
402
403 ### Alignment
404
405 Use alignment wherever it enhances the readability. See the following example:
406
407 ~~~~~{.cpp}
408 MyPackage_MyClass anObject;
409 Standard_Real     aMinimum = 0.0;
410 Standard_Integer  aVal     = theVal;
411 switch (aVal)
412 {
413   case 0:  computeSomething();              break;
414   case 12: computeSomethingElse (aMinimum); break;
415   case 3:
416   default: computeSomethingElseYet();       break;
417 }
418 ~~~~~
419
420 ### Indentation of comments
421
422 Comments should be indented in the same way as the code to which they refer or they can be in the same line if they are short.
423
424 The text of the comment should be separated from the slash character by a single space character.
425
426 See the following example:
427
428 ~~~~~{.cpp}
429 while (expression)   //bad comment
430 {
431   // this is a long multi-line comment
432   // which is really required
433   DoSomething();     // maybe, enough
434   DoSomethingMore(); // again
435 }
436 ~~~~~
437
438 ### Early return statement
439
440 Use an early return condition rather than collect indentations.
441
442 Write like this:
443
444 ~~~~~{.cpp}
445 Standard_Integer ComputeSumm (const Standard_Integer* theArray,
446                               const Standard_Size     theSize)
447 {
448   Standard_Integer aSumm = 0;
449   if (theArray == NULL || theSize == 0)
450   {
451     return 0;
452   }
453
454   ... computing summ ...
455   return aSumm;
456 }
457 ~~~~~
458
459 Rather than:
460
461 ~~~~~{.cpp}
462 Standard_Integer ComputeSumm (const Standard_Integer* theArray,
463                               const Standard_Size     theSize)
464 {
465   Standard_Integer aSumm = 0;
466   if (theArray != NULL && theSize != 0)
467   {
468     ... computing summ ...
469   }
470   return aSumm;
471 }
472 ~~~~~
473
474 This helps to improve readability and reduce the unnecessary indentation depth.
475
476 ### Trailing spaces
477
478 Trailing spaces should be removed whenever possible.
479 Spaces at the end of a line are useless and do not affect functionality.
480
481 ### Headers order
482
483 Split headers into groups: system headers, headers per each framework, project headers; sort the list of includes alphabetically.
484 Within the class source file, the class header file should be included first.
485
486 This rule improves readability, allows detecting useless multiple header inclusions and makes 3rd-party dependencies clearly visible.
487 Inclusion of class header on top verifies consistency of the header (e.g. that header file does not use any undefined declarations due to missing includes of dependencies).
488
489 An exception to the rule is ordering system headers generating a macros declaration conflicts (like "windows.h" or "X11/Xlib.h") - these headers should be placed in the way solving the conflict.
490
491 The source or header file should include only minimal set of headers necessary for compilation, without duplicates (considering nested includes).
492
493 ~~~~~{.cpp}
494 // the header file of implemented class
495 #include <PackageName_ClassName.hxx>
496
497 // OCCT headers
498 #include <gp_Pnt.hxx>
499 #include <gp_Vec.hxx>
500 #include <NCollection_List.hxx>
501
502 // Qt headers
503 #include <QDataStream>
504 #include <QString>
505
506 // system headers
507 #include <iostream>
508 #include <windows.h>
509 ~~~~~
510
511 @section occt_coding_rules_4 Documentation rules
512
513 The source code is one of the most important references for documentation.
514 The comments in the source code should be complete enough to allow understanding the corresponding code and to serve as basis for other documents.
515
516 The main reasons why the comments are regarded as documentation and should be maintained are:
517 - The comments are easy to reach -- they are always together with the source code;
518 - It is easy to update a description in the comment when the source is modified;
519 - The source by itself is a good context to describe various details that would require much more explanations in a separate document;
520 - As a summary, this is the most cost-effective documentation.
521
522 The comments should be compatible with Doxygen tool for automatic documentation generation (thus should use compatible tags).
523
524 ### Documenting classes [MANDATORY]
525
526 Each class should be documented in its header file (.hxx).
527 The comment should give enough details for the reader to understand the purpose of the class and the main way of work with it.
528
529 ### Documenting class methods [MANDATORY]
530
531 Each class or package method should be documented in the header file (.hxx).
532
533 The comment should explain the purpose of the method, its parameters, and returned value(s).
534 Accepted style is:
535
536 @verbatim
537 //! Method computes the square value.
538 //! @param theValue the input value
539 //! @return squared value
540 Standard_Export Standard_Real Square (Standard_Real theValue);
541 @endverbatim
542
543 ### Documenting C/C++ sources
544
545 It is very desirable to put comments in the C/C++ sources of the package/class.
546
547 They should be detailed enough to allow any person to understand what each part of code does.
548
549 It is recommended to comment all static functions (like methods in headers), and to insert at least one comment per each 10-100 lines in the function body.
550
551 There are also some rules that define how comments should be formatted, see @ref occt_coding_rules_3 "Formatting Rules".
552
553 Following these rules is important for good comprehension of the comments. Moreover, this approach  allows automatically generating user-oriented documentation directly from the commented sources.
554
555 @section occt_coding_rules_5 Application design
556
557 The following rules define the common style, which should be applied by any developer contributing to the open source.
558
559 ### Allow possible inheritance
560
561 Try to design general classes (objects) keeping possible inheritance in mind.
562 This rule means that the user who makes possible extensions of your class should not encounter problems of private implementation.
563 Try to use protected members and virtual methods wherever you expect extensions in the future.
564
565 ### Avoid friend declarations
566
567 Avoid using 'friend' classes or functions except for some specific cases (for example, iteration) 'Friend' declarations increase coupling.
568
569 ### Set/get methods
570
571 Avoid providing set/get methods for all fields of the class.
572 Intensive set/get functions break down encapsulation.
573
574 ### Hiding virtual functions [MANDATORY]
575
576 Avoid hiding a base class virtual function by a redefined function with a different signature.
577 Most of the compilers issue warning on this.
578
579 ### Avoid mixing error reporting strategies
580
581 Try not to mix different error indication/handling strategies (exceptions or returned values) on the same application level.
582
583 ### Minimize compiler warnings [MANDATORY]
584
585 When compiling the source pay attention to and try to minimize compiler warnings.
586
587 ### Avoid unnecessary inclusions
588
589 Try to minimize compilation dependencies by removing unnecessary inclusions.
590
591 @section occt_coding_rules_6 General C/C++ rules
592
593 This section defines the rules for writing a portable and maintainable C/C++ source code.
594
595 ### Wrapping of global variables [MANDATORY]
596
597 Use package or class methods returning reference to wrap global variables to reduce possible name space conflicts.
598
599 ### Avoid private members
600
601 Use *protected* members instead of *private* wherever reasonable to enable future extensions.
602 Use *private* fields if future extensions should be disabled.
603
604 ### Constants and inlines over defines [MANDATORY]
605
606 Use constant variables (const) and inline functions instead of defines (\#define).
607
608 ### Avoid explicit numerical values [MANDATORY]
609
610 Avoid usage of explicit numeric values. Use named constants and enumerations instead.
611 Numbers produce difficulties for reading and maintenance.
612
613 ### Three mandatory methods
614
615 If a class has a destructor, an assignment operator or a copy constructor, it usually needs the other two methods.
616
617 ### Virtual destructor
618
619 A class with virtual function(s) ought to have a virtual destructor.
620
621 ### Overriding virtual methods
622
623 Declaration of overriding method should contains specifiers "virtual" and "override"
624 (using Standard_OVERRIDE alias for compatibility with old compilers).
625
626 ~~~~~{.cpp}
627 class MyPackage_BaseClass
628 {
629
630 public:
631
632   Standard_EXPORT virtual Standard_Boolean Perform();
633
634 };
635
636 class MyPackage_MyClass : public MyPackage_BaseClass
637 {
638
639 public:
640
641   Standard_EXPORT virtual Standard_Boolean Perform() Standard_OVERRIDE;
642
643 };
644 ~~~~~
645
646 This makes class definition more clear (virtual methods become highlighted).
647
648 Declaration of interface using pure virtual functions protects against
649 incomplete inheritance at first level, but does not help when method is overridden multiple times within nested inheritance
650 or when method in base class is intended to be optional.
651
652 And here "override" specifier introduces additional protection against situations when interface changes might be missed
653 (class might contain old methods which will be never called).
654
655 ### Default parameter value
656
657 Do not redefine a default parameter value in an inherited function.
658
659 ### Use const modifier
660
661 Use *const* modifier wherever possible (functions parameters, return values, etc.)
662
663 ### Usage of goto [MANDATORY]
664 Avoid *goto* statement unless it is really needed.
665
666 ### Declaring variable in for() header
667
668 Declare a cycle variable in the header of the *for()* statement if not used out of cycle.
669
670 ~~~~~{.cpp}
671 Standard_Real aMinDist = Precision::Infinite();
672 for (NCollection_Sequence<gp_Pnt>::Iterator aPntIter (theSequence);
673      aPntIter.More(); aPntIter.Next())
674 {
675   aMinDist = Min (aMinDist, theOrigin.Distance (aPntIter.Value()));
676 }
677 ~~~~~
678
679 ### Condition statements within zero
680
681 Avoid usage of C-style comparison for non-boolean variables:
682
683 ~~~~~{.cpp}
684 void Function (Standard_Integer theValue,
685                Standard_Real*   thePointer)
686 {
687   if (!theValue)          // bad style - ambiguous logic
688   {
689     DoSome();
690   }
691
692   if (theValue == 0)      // OK
693   {
694     DoSome();
695   }
696
697   if (thePointer != NULL) // OK, predefined NULL makes pointer comparison cleaner to reader
698   {                       // (nullptr should be used instead as soon as C++11 will be available)
699     DoSome2();
700   }
701 }
702 ~~~~~
703
704 @section occt_coding_rules_7 Portability issues
705
706 This chapter contains rules that are critical for cross-platform portability.
707
708 ### Provide code portability [MANDATORY]
709
710 The source code must be portable to all platforms listed in the official 'Technical Requirements'.
711 The term 'portable' here means 'able to be built from source'.
712
713 The C++ source code should meet C++03 standard.
714 Any usage of compiler-specific features or further language versions (for example, C++11, until all major compilers on all supported platforms implement all its features) should be optional (used only with appropriate preprocessor checks) and non-exclusive (an alternative implementation compatible with other compilers should be provided).
715
716 ### Avoid usage of global variables [MANDATORY]
717
718 Avoid usage of global variables. Usage of global variables may cause problems when accessed from another shared library.
719
720 Use global (package or class) functions that return reference to static variable local to this function instead of global variables.
721
722 Another possible problem is the order of initialization of global variables defined in various libraries that may differ depending on platform, compiler and environment.
723
724 ### Avoid explicit basic types
725
726 Avoid explicit usage of basic types (*int*, *float*, *double*, etc.), use Open CASCADE Technology types from package *Standard: Standard_Integer, Standard_Real, Standard_ShortReal, Standard_Boolean, Standard_CString* and others or a specific *typedef* instead.
727
728 ### Use *sizeof()* to calculate sizes [MANDATORY]
729
730 Do not assume sizes of types. Use *sizeof()* instead to calculate sizes.
731
732 ### Empty line at the end of file [MANDATORY]
733
734 In accordance with C++03 standard source files should be trailed by an empty line.
735 It is recommended to follow this rule for any plain text files for consistency and for correct work of git difference tools.
736
737 @section occt_coding_rules_8 Stability issues
738
739 The rules listed in this chapter are important for stability of the programs that use Open CASCADE Technology libraries.
740
741 ### Use *OSD::SetSignal()* to catch exceptions
742
743 When using Open CASCADE Technology in an application, call *OSD::SetSignal()* function when the application is initialized.
744
745 This will install C handlers for run-time interrupt signals and exceptions, so that low-level exceptions (such as access violation, division by zero, etc.) will be redirected to C++ exceptions
746 that use *try {...} catch (Standard_Failure) {...}* blocks.
747
748 The above rule is especially important for robustness of modeling algorithms.
749
750 ### Cross-referenced handles
751
752 Take care about cycling of handled references to avoid chains, which will never be freed. For this purpose, use a pointer at one (subordinate) side. 
753
754 See the following example:
755
756 ~~~~{.cpp}
757     class Slave;
758
759     class Master : public Standard_Transient
760     {
761     ...
762       void SetSlave (const Handle(Slave)& theSlave)
763       { 
764         mySlave = theSlave;
765       }
766     ...
767     private:
768       Handle(Slave) theSlave; // smart pointer
769     ...
770     }
771
772     class Slave : public Standard_Transient
773     {
774     ...
775       void SetMaster (const Handle(Master)& theMaster)
776       { 
777         myMaster = theMaster.get();
778       }
779     ...
780     private:
781       Master* theMaster; // simple pointer
782     ...
783     }
784 ~~~~
785
786 ### C++ memory allocation
787
788 In C++ use *new* and *delete* operators instead of *malloc()* and *free()*. Try not to mix different memory allocation techniques.
789
790 ### Match *new* and *delete* [MANDATORY]
791
792 Use the same form of new and delete.
793
794 ~~~~~{.cpp}
795 aPtr1 = new TypeA[n];              ... ; delete[]        aPtr1;
796 aPtr2 = new TypeB();               ... ; delete          aPtr2;
797 aPtr3 = Standard::Allocate (4096); ... ; Standard::Free (aPtr3);
798 ~~~~~
799
800 ### Methods managing dynamical allocation [MANDATORY]
801
802 Define a destructor, a copy constructor and an assignment operator for classes with dynamically allocated memory.
803
804 ### Uninitialized variables [MANDATORY]
805
806 Every variable should be initialized.
807
808 ~~~~~{.cpp}
809 Standard_Integer aTmpVar1;     // bad
810 Standard_Integer aTmpVar2 = 0; // OK
811 ~~~~~
812
813 Uninitialized variables might be kept only within performance-sensitive code blocks and only when their initialization is guaranteed by subsequent code.
814
815 ### Do not hide global *new*
816
817 Avoid hiding the global *new* operator.
818
819 ### Assignment operator
820
821 In *operator=()* assign to all data members and check for assignment to self.
822
823 ### Float comparison
824
825 Don't check floats for equality or non-equality; check for GT, GE, LT or LE.
826
827 ~~~~~{.cpp}
828 if (Abs (theFloat1 - theFloat2) < theTolerance)
829 {
830   DoSome();
831 }
832 ~~~~~
833
834 Package *Precision* provides standard values for SI units and widely adopted by existing modeling algorithms:
835
836 - *Precision::Confusion()* for lengths in meters;
837 - *Precision::Angular()* for angles in radians.
838
839 as well as definition of infinite values within normal range of double precision:
840 - *Precision::Infinite()*
841 - *Precision::IsInfinite()*
842 - *Precision::IsPositiveInfinite()*
843 - *Precision::IsNegativeInfinite()*
844
845 ### Non-indexed iteration
846
847 Avoid usage of iteration over non-indexed collections of objects.
848 If such iteration is used, make sure that the result of the algorithm does not depend on the order of iterated items.
849
850 Since the order of iteration is unpredictable in case of a non-indexed collection of objects, it frequently leads to different behavior of the application from one run to another, thus embarrassing the debugging process.
851
852 It mostly concerns mapped objects for which pointers are involved in calculating the hash function. For example, the hash function of *TopoDS_Shape* involves the address of *TopoDS_TShape* object. Thus the order of the same shape in the *TopTools_MapOfShape* will vary in different sessions of the application. 
853
854 ### Do not throw in destructors
855
856 Do not throw from within a destructor.
857
858 ### Assigning to reference [MANDATORY]
859
860 Avoid the assignment of a temporary object to a reference. This results in a different behavior for different compilers on different platforms.
861
862 @section occt_coding_rules_9 Performance issues
863
864 These rules define the ways of avoiding possible loss of performance caused by ineffective programming.
865
866 ### Class fields alignment
867
868 Declare fields of a class in the decreasing order of their size for better alignment.
869 Generally, try to reduce misaligned accesses since they impact the performance (for example, on Intel machines).
870
871 ### Fields initialization order [MANDATORY]
872
873 List class data members in the constructor's initialization list in the order they are declared.
874
875 ~~~~~{.cpp}
876 class MyPackage_MyClass
877 {
878
879 public:
880
881   MyPackage_MyClass()
882   : myPropertyA (1),
883     myPropertyB (2) {}
884
885 // NOT
886 // : myPropertyB (2),
887 //   myPropertyA (1) {}
888
889 private:
890
891   Standard_Integer myPropertyA;
892   Standard_Integer myPropertyB;
893
894 };
895 ~~~~~
896
897 ### Initialization over assignment
898
899 Prefer initialization over assignment in class constructors.
900
901 ~~~~~{.cpp}
902 MyPackage_MyClass()
903 : myPropertyA (1)  // preferred
904 {
905   myPropertyB = 2; // not recommended
906 }
907 ~~~~~
908
909 ### Optimize caching
910
911 When programming procedures with extensive memory access, try to optimize them in terms of cache behavior. Here is an example of how the cache behavior can be impacted:
912
913 On x86 this code
914
915 ~~~~~{.cpp}
916 Standard_Real anArray[4096][2];
917 for (Standard_Integer anIter = 0; anIter < 4096; ++anIter)
918 {
919   anArray[anIter][0] = anArray[anIter][1];
920 }
921 ~~~~~
922
923 is more efficient then
924
925 ~~~~~{.cpp}
926 Standard_Real anArray[2][4096];
927 for (Standard_Integer anIter = 0; anIter < 4096; ++anIter)
928 {
929   anArray[0][anIter] = anArray[1][anIter];
930 }
931 ~~~~~
932
933 since linear access does not invalidate cache too often.
934
935 @section occt_coding_rules_10 Draw Harness command
936
937 Draw Harness provides TCL interface for OCCT algorithms.
938
939 There is no TCL wrapper over OCCT C++ classes, instead interface is provided through the set of TCL commands implemented in C++.
940
941 There is a list of common rules which should be followed to implement well-formed Draw Harness command.
942
943 ### Return value
944
945 Command should return 0 in most cases even if the executed algorithm has failed. Returning 1 would lead to a TCL exception, thus should be used in case of a command line syntax error and similar issues.
946
947 ### Validate input parameters
948
949 Command arguments should be validated before usage. The user should see a human-readable error description instead of a runtime exception from the executed algorithm.
950
951 ### Validate the number of input parameters
952
953 Command should warn the user about unknown arguments, including cases when extra parameters have been pushed for the command with a fixed number of arguments.
954
955 ~~~~~{.cpp}
956   if (theArgsNb != 3)
957   {
958     std::cout << "Syntax error - wrong number of arguments!\n";
959     return 1;
960   }
961
962   Standard_Integer anArgIter  = 1;
963   Standard_CString aResName   = theArgVec[anArgIter++];
964   Standard_CString aFaceName  = theArgVec[anArgIter++];
965   TopoDS_Shape     aFaceShape = DBRep::Get (aFaceName);
966   if (aFaceShape.IsNull()
967    || aFaceShape.ShapeType() != TopAbs_FACE)
968   {
969     std::cout << "Shape " << aFaceName << " is empty or not a Face!\n";
970     return 1;
971   }
972   DBRep::Set (aResName, aFaceShape);
973   return 0;
974 ~~~~~
975
976 ### Message printing
977
978 Informative messages should be printed into standard output *std::cout*, whilst command results (if any) -- into Draw Interpreter.
979
980 Information printed into Draw Interpreter should be well-structured to allow usage in TCL script.
981
982 ### Long list of arguments
983
984 Any command with a long list of obligatory parameters should be considered as ill-formed by design.
985 Optional parameters should start with flag name (with '-' prefix) and followed by its values:
986
987 ~~~~~{.tcl}
988 myCommand -flag1 value1 value2 -flag2 value3
989 ~~~~~
990
991 ### Arguments parser
992
993 - Integer values should be read using *Draw::Atoi()* function.
994 - Real values should be read using *Draw::Atof()* function.
995 - Flags names should be checked in case insensitive manner.
996
997 Functions *Draw::Atof()* and *Draw::Atoi()* support expressions and read values in C-locale.
998
999 ~~~~~{.cpp}
1000   Standard_Real aPosition[3] = {0.0, 0.0, 0.0};
1001   for (Standard_Integer anArgIter = 1; anArgIter < theArgsNb; ++anArgIter)
1002   {
1003     Standard_CString anArg = theArgVec[anArgIter];
1004     TCollection_AsciiString aFlag (anArg);
1005     aFlag.LowerCase(); //!< for case insensitive comparison
1006     if (aFlag == "position")
1007     {
1008       if ((anArgIt + 3) >= theArgsNb)
1009       {
1010         std::cerr << "Wrong syntax at argument '" << anArg << "'!\n";
1011         return 1;
1012       }
1013       aPosition[0] = Draw::Atof (theArgVec[++anArgIt]);
1014       aPosition[1] = Draw::Atof (theArgVec[++anArgIt]);
1015       aPosition[2] = Draw::Atof (theArgVec[++anArgIt]);
1016     }
1017     else
1018     {
1019       std::cout << "Syntax error! Unknown flag '" << anArg << "'\n";
1020       return 1;
1021     }
1022   }
1023 ~~~~~
1024
1025 @section occt_coding_rules_11 Examples
1026
1027 ### Sample documented class
1028
1029 @verbatim
1030 class Package_Class
1031 {
1032
1033 public: //! @name public methods
1034
1035   //! Method computes the square value.
1036   //! @param theValue the input value
1037   //! @return squared value
1038   Standard_Export Standard_Real Square (const Standard_Real theValue);
1039
1040 private: //! \@name private methods
1041
1042   //! Auxiliary method
1043   void increment();
1044
1045 private: //! \@name private fields
1046
1047   Standard_Integer myCounter; //!< usage counter
1048
1049 };
1050
1051
1052 @endverbatim
1053
1054 ~~~~~
1055 #include <Package_Class.hxx>
1056 // ==========================================================
1057 // function : Square
1058 // purpose  : Method computes the square value
1059 // ==========================================================
1060 Standard_Real Package_Class::Square (const Standard_Real theValue)
1061 {
1062   increment();
1063   return theValue * theValue;
1064 }
1065
1066 // ==========================================================
1067 // function : increment
1068 // purpose  :
1069 // ==========================================================
1070 void Package_Class::increment()
1071 {
1072   ++myCounter;
1073 }
1074 ~~~~~
1075
1076 ### TCL script for Draw Harness
1077
1078 ~~~~~{.tcl}
1079 # show fragments (solids) in shading with different colors
1080 proc DisplayColored {theShape} {
1081   set aSolids [uplevel #0 explode $theShape so]
1082   set aColorIter 0
1083   set THE_COLORS {red green blue1 magenta1 yellow cyan1 brown}
1084   foreach aSolIter $aSolids {
1085     uplevel #0 vdisplay         $aSolIter
1086     uplevel #0 vsetcolor        $aSolIter [lindex $THE_COLORS [expr [incr aColorIter] % [llength $THE_COLORS]]]
1087     uplevel #0 vsetdispmode     $aSolIter 1
1088     uplevel #0 vsetmaterial     $aSolIter plastic
1089     uplevel #0 vsettransparency $aSolIter 0.5
1090   }
1091 }
1092
1093 # load modules
1094 pload MODELING VISUALIZATION
1095
1096 # create boxes
1097 box bc  0 0 0 1 1 1
1098 box br  1 0 0 1 1 2
1099 compound bc br c
1100
1101 # show fragments (solids) in shading with different colors
1102 vinit View1
1103 vclear
1104 vaxo
1105 vzbufftrihedron
1106 DisplayColored c
1107 vfit
1108 vdump $imagedir/${casename}.png 512 512
1109 ~~~~~
1110
1111 ### GLSL program:
1112 ~~~~~{.fs}
1113 vec3 Ambient;  //!< Ambient  contribution of light sources
1114 vec3 Diffuse;  //!< Diffuse  contribution of light sources
1115 vec3 Specular; //!< Specular contribution of light sources
1116
1117 //! Computes illumination from light sources
1118 vec4 ComputeLighting (in vec3 theNormal,
1119                       in vec3 theView,
1120                       in vec4 thePoint)
1121 {
1122   // clear the light intensity accumulators
1123   Ambient  = occLightAmbient.rgb;
1124   Diffuse  = vec3 (0.0);
1125   Specular = vec3 (0.0);
1126   vec3 aPoint = thePoint.xyz / thePoint.w;
1127   for (int anIndex = 0; anIndex < occLightSourcesCount; ++anIndex)
1128   {
1129     int aType = occLight_Type (anIndex);
1130     if (aType == OccLightType_Direct)
1131     {
1132       directionalLight (anIndex, theNormal, theView);
1133     }
1134     else if (aType == OccLightType_Point)
1135     {
1136       pointLight (anIndex, theNormal, theView, aPoint);
1137     }
1138   }
1139
1140   return vec4 (Ambient,  1.0) * occFrontMaterial_Ambient()
1141        + vec4 (Diffuse,  1.0) * occFrontMaterial_Diffuse()
1142        + vec4 (Specular, 1.0) * occFrontMaterial_Specular();
1143 }
1144
1145 //! Entry point to the Fragment Shader
1146 void main()
1147 {
1148   gl_FragColor = computeLighting (normalize (Normal),
1149                                   normalize (View),
1150                                   Position);
1151 }
1152 ~~~~~