0024514: Unclear guidelines to report issues in Mantis

[occt.git] / dox / dev_guides / contribution / coding_rules.md

diff --git a/dox/dev_guides/contribution/coding_rules.md b/dox/dev_guides/contribution/coding_rules.md
index 5ade76f..36e6d40 100644 (file)
--- a/dox/dev_guides/contribution/coding_rules.md
+++ b/dox/dev_guides/contribution/coding_rules.md
@@ -1,4 +1,4 @@
-Coding Rules {#dev_guides__coding_rules}
+Coding Rules {#occt_dev_guides__coding_rules}
 ======================================
 
 @tableofcontents
@@ -163,7 +163,7 @@ Standard_Integer myCounter; // This is preferred
 ### Names of global variables
 
 It is strongly recommended to avoid defining any global variables.
-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 *_my*.
+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>.
 
 See the following examples:
 
@@ -238,7 +238,7 @@ Prefer C++ style comments in C++ sources.
 
 ### Commenting out unused code
 
-Delete unused code instead of commenting it or using #define.
+Delete unused code instead of commenting it or using \#define.
 
 ### Indentation in sources [MANDATORY]
 
@@ -296,19 +296,19 @@ Each descriptive block should contain at least a function name and purpose descr
 See the following example:
 
 ~~~~~{.cpp}
-// ----------------------------------------------
+// =======================================================================
 // function : TellMeSmthGood
 // purpose  : Gives me good news
-// ----------------------------------------------
+// =======================================================================
 void TellMeSmthGood()
 {
   ...
 }
 
-// ----------------------------------------------
+// =======================================================================
 // function : TellMeSmthBad
 // purpose  : Gives me bad news
-// ----------------------------------------------
+// =======================================================================
 void TellMeSmthBad()
 {
   ...
@@ -486,7 +486,7 @@ They should be detailed enough to allow any person to understand what each part
 
 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.
 
-There are also some rules that define how comments should be formatted, see <a href="#occt_coding_rules_3">Formatting Rules</a>.
+There are also some rules that define how comments should be formatted, see @ref occt_coding_rules_3 "Formatting Rules".
 
 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.
 
@@ -541,7 +541,7 @@ Use *private* fields if future extensions should be disabled.
 
 ### Constants and inlines over defines [MANDATORY]
 
-Use constant variables (const) and inline functions instead of defines (#define).
+Use constant variables (const) and inline functions instead of defines (\#define).
 
 ### Avoid explicit numerical values [MANDATORY]
 
@@ -556,6 +556,41 @@ If a class has a destructor, an assignment operator or a copy constructor, it us
 
 A class with virtual function(s) ought to have a virtual destructor.
 
+### Overriding virtual methods
+
+Declaration of overriding method should contains specifiers "virtual" and "override"
+(using Standard_OVERRIDE alias for compatibility with old compilers).
+
+~~~~~{.cpp}
+class MyPackage_BaseClass
+{
+
+public:
+
+  Standard_EXPORT virtual Standard_Boolean Perform();
+
+};
+
+~~~~~{.cpp}
+class MyPackage_MyClass : public MyPackage_BaseClass
+{
+
+public:
+
+  Standard_EXPORT virtual Standard_Boolean Perform() Standard_OVERRIDE;
+
+};
+~~~~~
+
+This makes class definition more clear (virtual methods become highlighted).
+
+Declaration of interface using pure virtual functions protects against
+incomplete inheritance at first level, but does not help when method is overridden multiple times within nested inheritance
+or when method in base class is intended to be optional.
+
+And here "override" specifier introduces additional protection against situations when interface changes might be missed
+(class might contain old methods which will be never called).
+
 ### Default parameter value
 
 Do not redefine a default parameter value in an inherited function.