1 Coding Rules {#occt_dev_guides__coding_rules}
2 ======================================
6 @section occt_coding_rules_1 Introduction
8 The purpose of this document is to define a common programming style for Open CASCADE Technology.
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.
12 OCCT programming style follows common and appropriate best practices, so some guidelines have been excerpted from the public domain.
14 The guide can be improved in the future as new ideas and enhancements are added.
16 @subsection occt_coding_rules_1_1 Scope of the document
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:
22 - TCL scripts and test cases
24 @section occt_coding_rules_2 Naming Conventions
26 @subsection occt_coding_rules_2_1 General naming rules
28 The names considered in this section mainly refer to the interface of Open CASCADE Technology libraries or source code itself.
30 ### International language [MANDATORY]
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.
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 - 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.
45 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.
46 For example, method *GetCoord* returns a triple of real values and is defined for directions, vectors and points. The logical connection is obvious.
49 Camel Case style is preferred for names.
53 Standard_Integer awidthofbox; // this is bad
54 Standard_Integer width_of_box; // this is bad
55 Standard_Integer aWidthOfBox; // this is OK
58 @subsection occt_coding_rules_2_2 Names of development units
60 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.
62 ### No underscores in unit names [MANDATORY]
64 Names of units should not contain underscores, unless the use of underscores is allowed explicitly.
66 ### File name extensions [MANDATORY]
68 The following extensions should be used for source files, depending on their type:
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)
75 ### Prefix for toolkit names [MANDATORY]
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*).
81 Usually 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 "_".
83 Thus, the names of files containing sources of C++ classes that belong to a package are constructed according to the following template:
86 <package-name>_<class-name>.cxx (or .hxx, or .cdl)
89 For example, file *Adaptor2d_Curve2d.cxx* belongs to the package *Adaptor2d*
91 Files that contain sources related to the whole unit are called by the unit name with appropriate extension.
93 ### Names of functions
95 The term **function** here is defined as:
98 - Any non-member procedure or function
100 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.
104 class MyPackage_MyClass
109 Standard_Integer Value() const;
110 void SetValue (const Standard_Integer theValue);
114 void setIntegerValue (const Standard_Integer theValue);
119 @subsection occt_coding_rules_2_3 Names of variables
121 There are several rules that describe currently accepted practices for naming variables.
123 ### Naming of variables
125 Name of a variable should not conflict with the existing or possible global names (for packages, macros, functions, global variables, etc.).
127 The name of a variable should not start with an underscore.
129 See the following examples:
132 Standard_Integer Elapsed_Time = 0; // this is bad - possible class name
133 Standard_Integer gp = 0; // this is bad - existing package name
134 Standard_Integer aGp = 0; // this is OK
135 Standard_Integer _KERNEL = 0; // this is bad
136 Standard_Integer THE_KERNEL = 0; // this is OK
139 ### Names of function parameters
141 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.
143 See the following examples:
146 void Package_MyClass::MyFunction (const gp_Pnt& p); // this is bad
147 void Package_MyClass::MyFunction (const gp_Pnt& theP); // this is OK
148 void Package_MyClass::MyFunction (const gp_Pnt& thePoint); // this is preferred
151 ### Names of class member variables
153 The name of a class member variable should start with prefix *my* followed by the meaningful of the name starting with a capital letter.
155 See the following examples:
158 Standard_Integer counter; // This is bad
159 Standard_Integer myC; // This is OK
160 Standard_Integer myCounter; // This is preferred
163 ### Names of global variables
165 It is strongly recommended to avoid defining any global variables.
166 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>.
168 See the following examples:
171 Standard_Integer MyPackage_myGlobalVariable = 0;
172 Standard_Integer MyPackage_MyClass_myGlobalVariable = 0;
175 Static constants within the file should be written in upper-case and begin with prefix *THE_*:
179 static const Standard_Real THE_CONSTANT_COEF = 3.14;
183 ### Names of local variables
185 The name of a local variable should be distinguishable from the name of a function parameter, a class member variable and a global variable.
187 It is preferred to prefix local variable names with *a* and *an* (or *is*, *to* and *has* for Boolean variables).
189 See the following example:
192 Standard_Integer theI; // this is bad
193 Standard_Integer i; // this is bad
194 Standard_Integer index; // this is bad
195 Standard_Integer anIndex; // this is OK
198 ### Avoid dummy names
199 Avoid dummy names, such as <i>i, j, k</i>. Such names are meaningless and easy to mix up.
201 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.
203 See the following examples for preferred style:
206 void Average (const Standard_Real** theArray,
207 Standard_Integer theRowsNb,
208 Standard_Integer theRowLen,
209 Standard_Real& theResult)
212 for (Standard_Integer aRow = 0; aRow < aRowsNb; ++aRow)
214 for (Standard_Integer aCol = 0; aCol < aRowLen; ++aCol)
216 theResult += theArray[aRow][aCol];
218 theResult /= Standard_Real(aRowsNb * aRowLen);
223 @section occt_coding_rules_3 Formatting rules
225 To improve the open source readability and, consequently, maintainability, the following set of rules is applied.
227 ### International language [MANDATORY]
229 All comments in all sources must be in English.
233 Try to stay within the limit of 120 characters per line in all sources.
235 ### C++ style comments
237 Prefer C++ style comments in C++ sources.
239 ### Commenting out unused code
241 Delete unused code instead of commenting it or using \#define.
243 ### Indentation in sources [MANDATORY]
245 Indentation in all sources should be set to two space characters.
246 Use of tabulation characters for indentation is disallowed.
248 ### Separating spaces
250 Punctuation 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:
256 while (true) // NOT: while( true ) ...
258 DoSomething (theA, theB, theC, theD); // NOT: DoSomething(theA,theB,theC,theD);
260 for (anIter = 0; anIter < 10; ++anIter) // NOT: for (anIter=0;anIter<10;++anIter){
262 theA = (theB + theC) * theD; // NOT: theA=(theB+theC)*theD
266 ### Separate logical blocks
268 Separate logical blocks of code with one blank line and comments.
270 See the following example:
274 Standard_Integer anArgsNb = argCount();
275 if (anArgsNb < 3 || isSmthInvalid)
277 return THE_ARG_INVALID;
280 // read and check header
289 Notice that multiple blank lines should be avoided.
291 ### Separate function bodies [MANDATORY]
293 Use function descriptive blocks to separate function bodies from each other.
294 Each descriptive block should contain at least a function name and purpose description.
296 See the following example:
299 // =======================================================================
300 // function : TellMeSmthGood
301 // purpose : Gives me good news
302 // =======================================================================
303 void TellMeSmthGood()
308 // =======================================================================
309 // function : TellMeSmthBad
310 // purpose : Gives me bad news
311 // =======================================================================
318 ### Block layout [MANDATORY]
319 Figure brackets <i>{ }</i> and each operator <i>(for, if, else, try, catch)</i> should be written on a dedicated line.
321 In general, the layout should be as follows:
330 Entering a block increases and leaving a block decreases the indentation by one tabulation.
332 ### Single-line operators
334 Single-line conditional operators <i>(if, while, for,</i> etc.) can be written without brackets on the following line.
337 if (!myIsInit) return Standard_False; // bad
339 if (thePtr == NULL) // OK
340 return Standard_False;
342 if (!theAlgo.IsNull()) // preferred
348 Having all code in the same line is less convenient for debugging.
352 Use alignment wherever it enhances the readability. See the following example:
355 MyPackage_MyClass anObject;
356 Standard_Real aMinimum = 0.0;
357 Standard_Integer aVal = theVal;
360 case 0: computeSomething(); break;
361 case 12: computeSomethingElse (aMinimum); break;
363 default: computeSomethingElseYet(); break;
367 ### Indentation of comments
369 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.
371 The text of the comment should be separated from the slash character by a single space character.
373 See the following example:
376 while (expression) //bad comment
378 // this is a long multi-line comment
379 // which is really required
380 DoSomething(); // maybe, enough
381 DoSomethingMore(); // again
385 ### Early return statement
387 Use an early return condition rather than collect indentations.
392 Standard_Integer ComputeSumm (const Standard_Integer* theArray,
393 const Standard_Size theSize)
395 Standard_Integer aSumm = 0;
396 if (theArray == NULL || theSize == 0)
401 ... computing summ ...
409 Standard_Integer ComputeSumm (const Standard_Integer* theArray,
410 const Standard_Size theSize)
412 Standard_Integer aSumm = 0;
413 if (theArray != NULL && theSize != 0)
415 ... computing summ ...
421 This helps to improve readability and reduce the unnecessary indentation depth.
425 Trailing spaces should be removed whenever possible.
426 Spaces at the end of a line are useless and do not affect functionality.
430 Split headers into groups: system headers, headers per each framework, project headers; sort the list of includes alphabetically.
432 This rule improves readability, allows detecting useless multiple header inclusions and makes 3rd-party dependencies clearly visible.
440 #include <QDataStream>
444 #include <gp_Pnt.hxx>
445 #include <gp_Vec.hxx>
446 #include <NCollection_List.hxx>
449 @section occt_coding_rules_4 Documentation rules
451 The source code is one of the most important references for documentation.
452 The comments in the source code should be complete enough to allow understanding the corresponding code and to serve as basis for other documents.
454 The 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.
460 The comments should be compatible with Doxygen tool for automatic documentation generation (thus should use compatible tags).
462 ### Documenting classes [MANDATORY]
464 Each class should be documented in its header file (.hxx or .cdl).
465 The comment should give enough details for the reader to understand the purpose of the class and the main way of work with it.
467 ### Documenting class methods [MANDATORY]
469 Each class or package method should be documented in the header file (.hxx or .cdl).
471 The comment should explain the purpose of the method, its parameters, and returned value(s).
475 //! Method computes the square value.
476 //! @param theValue the input value
477 //! @return squared value
478 Standard_Export Standard_Real Square (Standard_Real theValue);
481 ### Documenting C/C++ sources
483 It is very desirable to put comments in the C/C++ sources of the package/class.
485 They should be detailed enough to allow any person to understand what each part of code does.
487 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.
489 There are also some rules that define how comments should be formatted, see <a href="#occt_coding_rules_3">Formatting Rules</a>.
491 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.
493 @section occt_coding_rules_5 Application design
495 The following rules define the common style, which should be applied by any developer contributing to the open source.
497 ### Allow possible inheritance
499 Try to design general classes (objects) keeping possible inheritance in mind.
500 This rule means that the user who makes possible extensions of your class should not encounter problems of private implementation.
501 Try to use protected members and virtual methods wherever you expect extensions in the future.
503 ### Avoid friend declarations
505 Avoid using 'friend' classes or functions except for some specific cases (for example, iteration) 'Friend' declarations increase coupling.
509 Avoid providing set/get methods for all fields of the class.
510 Intensive set/get functions break down encapsulation.
512 ### Hiding virtual functions [MANDATORY]
514 Avoid hiding a base class virtual function by a redefined function with a different signature.
515 Most of the compilers issue warning on this.
517 ### Avoid mixing error reporting strategies
519 Try not to mix different error indication/handling strategies (exceptions or returned values) on the same application level.
521 ### Minimize compiler warnings [MANDATORY]
523 When compiling the source pay attention to and try to minimize compiler warnings.
525 ### Avoid unnecessary inclusions
527 Try to minimize compilation dependencies by removing unnecessary inclusions.
529 @section occt_coding_rules_6 General C/C++ rules
531 This section defines the rules for writing a portable and maintainable C/C++ source code.
533 ### Wrapping of global variables [MANDATORY]
535 Use package or class methods returning reference to wrap global variables to reduce possible name space conflicts.
537 ### Avoid private members
539 Use *protected* members instead of *private* wherever reasonable to enable future extensions.
540 Use *private* fields if future extensions should be disabled.
542 ### Constants and inlines over defines [MANDATORY]
544 Use constant variables (const) and inline functions instead of defines (\#define).
546 ### Avoid explicit numerical values [MANDATORY]
548 Avoid usage of explicit numeric values. Use named constants and enumerations instead.
549 Numbers produce difficulties for reading and maintenance.
551 ### Three mandatory methods
553 If a class has a destructor, an assignment operator or a copy constructor, it usually needs the other two methods.
555 ### Virtual destructor
557 A class with virtual function(s) ought to have a virtual destructor.
559 ### Overriding virtual methods
561 Declaration of overriding method should contains specifiers "virtual" and "override"
562 (using Standard_OVERRIDE alias for compatibility with old compilers).
565 class MyPackage_BaseClass
570 Standard_EXPORT virtual Standard_Boolean Perform();
575 class MyPackage_MyClass : public MyPackage_BaseClass
580 Standard_EXPORT virtual Standard_Boolean Perform() Standard_OVERRIDE;
585 This makes class definition more clear (virtual methods become highlighted).
587 Declaration of interface using pure virtual functions protects against
588 incomplete inheritance at first level, but does not help when method is overridden multiple times within nested inheritance
589 or when method in base class is intended to be optional.
591 And 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).
594 ### Default parameter value
596 Do not redefine a default parameter value in an inherited function.
598 ### Use const modifier
600 Use *const* modifier wherever possible (functions parameters, return values, etc.)
602 ### Usage of goto [MANDATORY]
603 Avoid *goto* statement unless it is really needed.
605 ### Declaring variable in for() header
607 Declare a cycle variable in the header of the *for()* statement if not used out of cycle.
610 Standard_Real aMinDist = Precision::Infinite();
611 for (NCollection_Sequence<gp_Pnt>::Iterator aPntIter (theSequence);
612 aPntIter.More(); aPntIter.Next())
614 aMinDist = Min (aMinDist, theOrigin.Distance (aPntIter.Value()));
618 ### Condition statements within zero
620 Avoid usage of C-style comparison for non-boolean variables:
623 void Function (Standard_Integer theValue,
624 Standard_Real* thePointer)
626 if (!theValue) // bad style - ambiguous logic
631 if (theValue == 0) // OK
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)
643 @section occt_coding_rules_7 Portability issues
645 This chapter contains rules that are critical for cross-platform portability.
647 ### Provide code portability [MANDATORY]
649 The source code must be portable to all platforms listed in the official 'Technical Requirements'.
650 The term 'portable' here means 'able to be built from source'.
652 The C++ source code should meet C++03 standard.
653 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).
655 ### Avoid usage of global variables [MANDATORY]
657 Avoid usage of global variables. Usage of global variables may cause problems when accessed from another shared library.
659 Use global (package or class) functions that return reference to static variable local to this function instead of global variables.
661 Another possible problem is the order of initialization of global variables defined in various libraries that may differ depending on platform, compiler and environment.
663 ### Avoid explicit basic types
665 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.
667 ### Use *sizeof()* to calculate sizes [MANDATORY]
669 Do not assume sizes of types. Use *sizeof()* instead to calculate sizes.
671 ### Empty line at the end of file [MANDATORY]
673 In accordance with C++03 standard source files should be trailed by an empty line.
674 It is recommended to follow this rule for any plain text files for consistency and for correct work of git difference tools.
676 @section occt_coding_rules_8 Stability issues
678 The rules listed in this chapter are important for stability of the programs that use Open CASCADE Technology libraries.
680 ### Use *OSD::SetSignal()* to catch exceptions
682 When using Open CASCADE Technology in an application, call *OSD::SetSignal()* function when the application is initialized.
684 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
685 that use *try {...} catch (Standard_Failure) {...}* blocks.
687 The above rule is especially important for robustness of modeling algorithms.
689 ### Cross-referenced handles
691 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.
693 See the following example:
699 class MySecondHandle;
700 pointer MySecondPointer to MySecondHandle;
704 In *MyPackage_MyFirstHandle.cdl* :
707 class MyFirstHandle from MyPackage
711 SetSecondHandleA (me: mutable; theSecond: MySecondHandle from MyPackage);
712 SetSecondHandleB (me: mutable; theSecond: MySecondHandle from MyPackage);
716 mySecondHandle : MySecondHandle from MyPackage;
717 mySecondPointer : MySecondPointer from MyPackage;
719 end MyFirstHandle from MyPackage;
722 In *MyPackage_MySecondHandle.cdl* :
725 class MySecondHandle from MyPackage
729 SetFirstHandle (me: mutable; theFirst: MyFirstHandle from MyPackage);
733 myFirstHandle : MyFirstHandle from MyPackage;
735 end MySecondHandle from MyPackage;
743 Handle(MyPackage_MyFirstHandle) anObj1 = new MyPackage_MyFirstHandle();
744 Handle(MyPackage_MySecondHandle) anObj2 = new MyPackage_MySecondHandle();
745 Handle(MyPackage_MySecondHandle) anObj3 = new MyPackage_MySecondHandle();
747 anObj1->SetSecondHandleA(anObj2);
748 anObj1->SetSecondHandleB(anObj3);
749 anObj2->SetFirstHandle(anObj1);
750 anObj3->SetFirstHandle(anObj1);
752 // memory is not freed here !!!
756 // memory is freed here
761 ### C++ memory allocation
763 In C++ use *new* and *delete* operators instead of *malloc()* and *free()*. Try not to mix different memory allocation techniques.
765 ### Match *new* and *delete* [MANDATORY]
767 Use the same form of new and delete.
770 aPtr1 = new TypeA[n]; ... ; delete[] aPtr1;
771 aPtr2 = new TypeB(); ... ; delete aPtr2;
772 aPtr3 = Standard::Allocate (4096); ... ; Standard::Free (aPtr3);
775 ### Methods managing dynamical allocation [MANDATORY]
777 Define a destructor, a copy constructor and an assignment operator for classes with dynamically allocated memory.
779 ### Uninitialized variables [MANDATORY]
781 Every variable should be initialized.
784 Standard_Integer aTmpVar1; // bad
785 Standard_Integer aTmpVar2 = 0; // OK
788 Uninitialized variables might be kept only within performance-sensitive code blocks and only when their initialization is guaranteed by subsequent code.
790 ### Do not hide global *new*
792 Avoid hiding the global *new* operator.
794 ### Assignment operator
796 In *operator=()* assign to all data members and check for assignment to self.
800 Don't check floats for equality or non-equality; check for GT, GE, LT or LE.
803 if (Abs (theFloat1 - theFloat2) < theTolerance)
809 Package *Precision* provides standard values for SI units and widely adopted by existing modeling algorithms:
811 - *Precision::Confusion()* for lengths in meters;
812 - *Precision::Angular()* for angles in radians.
814 as well as definition of infinite values within normal range of double precision:
815 - *Precision::Infinite()*
816 - *Precision::IsInfinite()*
817 - *Precision::IsPositiveInfinite()*
818 - *Precision::IsNegativeInfinite()*
820 ### Non-indexed iteration
822 Avoid usage of iteration over non-indexed collections of objects.
823 If such iteration is used, make sure that the result of the algorithm does not depend on the order of iterated items.
825 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.
827 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.
829 ### Do not throw in destructors
831 Do not throw from within a destructor.
833 ### Assigning to reference [MANDATORY]
835 Avoid the assignment of a temporary object to a reference. This results in a different behavior for different compilers on different platforms.
837 @section occt_coding_rules_9 Performance issues
839 These rules define the ways of avoiding possible loss of performance caused by ineffective programming.
841 ### Class fields alignment
843 Declare fields of a class in the decreasing order of their size for better alignment.
844 Generally, try to reduce misaligned accesses since they impact the performance (for example, on Intel machines).
846 ### Fields initialization order [MANDATORY]
848 List class data members in the constructor's initialization list in the order they are declared.
851 class MyPackage_MyClass
861 // : myPropertyB (2),
862 // myPropertyA (1) {}
866 Standard_Integer myPropertyA;
867 Standard_Integer myPropertyB;
872 ### Initialization over assignment
874 Prefer initialization over assignment in class constructors.
878 : myPropertyA (1) // preferred
880 myPropertyB = 2; // not recommended
886 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:
891 Standard_Real anArray[4096][2];
892 for (Standard_Integer anIter = 0; anIter < 4096; ++anIter)
894 anArray[anIter][0] = anArray[anIter][1];
898 is more efficient then
901 Standard_Real anArray[2][4096];
902 for (Standard_Integer anIter = 0; anIter < 4096; ++anIter)
904 anArray[0][anIter] = anArray[1][anIter];
908 since linear access does not invalidate cache too often.
910 @section occt_coding_rules_10 Draw Harness command
912 Draw Harness provides TCL interface for OCCT algorithms.
914 There is no TCL wrapper over OCCT C++ classes, instead interface is provided through the set of TCL commands implemented in C++.
916 There is a list of common rules which should be followed to implement well-formed Draw Harness command.
920 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.
922 ### Validate input parameters
924 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.
926 ### Validate the number of input parameters
928 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.
933 std::cout << "Syntax error - wrong number of arguments!\n";
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)
944 std::cout << "Shape " << aFaceName << " is empty or not a Face!\n";
947 DBRep::Set (aResName, aFaceShape);
953 Informative messages should be printed into standard output *std::cout*, whilst command results (if any) - into Draw Interpreter.
955 Information printed into Draw Interpreter should be well-structured to allow usage in TCL script.
957 ### Long list of arguments
959 Any command with a long list of obligatory parameters should be considered as ill-formed by design.
960 Optional parameters should start with flag name (with '-' prefix) and followed by its values:
963 myCommand -flag1 value1 value2 -flag2 value3
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.
972 Functions *Draw::Atof()* and *Draw::Atoi()* support expressions and read values in C-locale.
975 Standard_Real aPosition[3] = {0.0, 0.0, 0.0};
976 for (Standard_Integer anArgIter = 1; anArgIter < theArgsNb; ++anArgIter)
978 Standard_CString anArg = theArgVec[anArgIter];
979 TCollection_AsciiString aFlag (anArg);
980 aFlag.LowerCase(); //!< for case insensitive comparison
981 if (aFlag == "position")
983 if ((anArgIt + 3) >= theArgsNb)
985 std::cerr << "Wrong syntax at argument '" << anArg << "'!\n";
988 aPosition[0] = Draw::Atof (theArgVec[++anArgIt]);
989 aPosition[1] = Draw::Atof (theArgVec[++anArgIt]);
990 aPosition[2] = Draw::Atof (theArgVec[++anArgIt]);
994 std::cout << "Syntax error! Unknown flag '" << anArg << "'\n";
1000 @section occt_coding_rules_11 Examples
1002 ### Sample documented class
1008 public: //! @name public methods
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);
1015 private: //! \@name private methods
1017 //! Auxiliary method
1020 private: //! \@name private fields
1022 Standard_Integer myCounter; //!< usage counter
1030 #include <Package_Class.hxx>
1031 // ==========================================================
1032 // function : Square
1033 // purpose : Method computes the square value
1034 // ==========================================================
1035 Standard_Real Package_Class::Square (const Standard_Real theValue)
1038 return theValue * theValue;
1041 // ==========================================================
1042 // function : increment
1044 // ==========================================================
1045 void Package_Class::increment()
1051 ### TCL script for Draw Harness
1054 # show fragments (solids) in shading with different colors
1055 proc DisplayColored {theShape} {
1056 set aSolids [uplevel #0 explode $theShape so]
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
1069 pload MODELING VISUALIZATION
1076 # show fragments (solids) in shading with different colors
1083 vdump $imagedir/${casename}.png 512 512
1088 vec3 Ambient; //!< Ambient contribution of light sources
1089 vec3 Diffuse; //!< Diffuse contribution of light sources
1090 vec3 Specular; //!< Specular contribution of light sources
1092 //! Computes illumination from light sources
1093 vec4 ComputeLighting (in vec3 theNormal,
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)
1104 int aType = occLight_Type (anIndex);
1105 if (aType == OccLightType_Direct)
1107 directionalLight (anIndex, theNormal, theView);
1109 else if (aType == OccLightType_Point)
1111 pointLight (anIndex, theNormal, theView, aPoint);
1115 return vec4 (Ambient, 1.0) * occFrontMaterial_Ambient()
1116 + vec4 (Diffuse, 1.0) * occFrontMaterial_Diffuse()
1117 + vec4 (Specular, 1.0) * occFrontMaterial_Specular();
1120 //! Entry point to the Fragment Shader
1123 gl_FragColor = computeLighting (normalize (Normal),