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