note about VMS linker case insensitivity added

[wxWidgets.git] / docs / html / standard.htm

diff --git a/docs/html/standard.htm b/docs/html/standard.htm
index fa5270c36eb3846ee4d6c210c4b21ebd0cc11773..6cc90a906252f2248d2d9c762a7419c2d17b50b9 100644 (file)
--- a/docs/html/standard.htm
+++ b/docs/html/standard.htm
@@ -59,8 +59,8 @@ C++ portability guide</A> by David Williams.
     <LI><A HREF="#no_warnings">Turn on all warnings and eradicate them</A></LI>
     <LI><A HREF="#no_assume_sizeof">Don't rely on <TT>sizeof(int) == 2</TT>...</A></LI>
     <LI><A HREF="#no_assignment_in_if">No assignments in conditional expressions</A></LI>
-    <LI><A HREF="#no_comment_code">Use <TT>#if 0</TT> rather than comments to temporarily
-                    disable blocks of code</A></LI>
+    <LI><A HREF="#no_comment_code">Use <TT>#if 0</TT> rather than comments to temporarily disable blocks of code</A></LI>
+    <LI><A HREF="#no_overloaded_virtuals">Avoid overloaded virtual functions</A></LI>
     <LI><A HREF="#no_extra_semicolon">Don't use extra semi-colons on top level</A></LI>
   </OL>
   <BR>
@@ -71,15 +71,14 @@ C++ portability guide</A> by David Williams.
     <LI><A HREF="#no_carriagereturn">Avoid carriage returns in cross-platform code</A></LI>
     <LI><A HREF="#no_caps_in_filenames">Use only lower letter filenames</A></LI>
     <LI><A HREF="#no_incomplete_files">Terminate the files with a new-line</A></LI>
+    <LI><A HREF="#no_case_only_diff">Avoid globals differing by case only</A></LI>
   </OL>
   <BR>
   <LI>Style choices</LI>
   <OL>
     <LI><A HREF="#naming_conv">Naming conventions: use <TT>m_</TT> for members</A></LI>
-    <LI><A HREF="#no_void_param">Don't use <TT>void</TT> for functions without
-                    arguments</A></LI>
-    <LI><A HREF="#no_const_int">Don't use <TT>const</TT> for non pointer/reference
-                    arguments</A></LI>
+    <LI><A HREF="#no_void_param">Don't use <TT>void</TT> for functions without arguments</A></LI>
+    <LI><A HREF="#no_const_int">Don't use <TT>const</TT> for non pointer/reference arguments</A></LI>
   </OL>
 </UL>
 
@@ -106,8 +105,7 @@ C++ portability guide</A> by David Williams.
   <LI>More about naming conventions</LI>
   <OL>
     <LI><A HREF="#wx_prefix">Use wx or WX prefix for all public symbols</A></LI>
-    <LI><A HREF="#wxdllexport">Use WXDLLEXPORT with all classes/functions in
-                               wxMSW/common code</A></LI>
+    <LI><A HREF="#wxdllexport">Use WXDLLEXPORT with all classes/functions in wxMSW/common code</A></LI>
     <LI><A HREF="#set_get">Use Set/Get prefixes for accessors</A></LI>
     <LI><A HREF="#constants">wxNAMING_CONSTANTS</A></LI>
   </OL>
@@ -464,6 +462,70 @@ instead of
 The reason is simple: if there are any <TT>/* ... */</TT> comments inside
 <TT>...</TT> the second version will, of course, miserably fail.
 
+    <P><LI><A NAME="no_overloaded_virtuals"></A><B>Avoid overloaded virtual functions</B></LI><P>
+
+You should avoid having overloaded virtual methods in a base class because if
+any of them is overriden in a derived class, then all others must be overriden
+as well or it would be impossible to call them on an object of derived class.
+
+For example, the following code:
+
+<PRE>
+    class Base
+    {
+    public:
+        virtual void Read(wxFile& file);
+        virtual void Read(const wxString& filename);
+    };
+
+    class Derived : public Base
+    {
+    public:
+        virtual void Read(wxFile& file) { ... }
+    };
+
+    ...
+
+    Derived d;
+    d.Read("some_filename");    // compile error here!
+</PRE>
+
+will fail to compile because the base class function taking <TT>filename</TT>
+is hidden by the virtual function overriden in the derived class (this is
+known as [virtual] function name hiding problem in C++).
+
+<P>
+The standard solution to this problem in wxWindows (where we have such
+situations quite often) is to make both <TT>Read()</TT> functions not virtual
+and introduce a single virtual function <TT>DoRead()</TT>. Usually, it makes
+sense because the function taking a filename is (again, usually) implemented
+in terms of the function reading from a file anyhow (but making only this
+functions not virtual won't solve the above problem!).
+<P>
+So, the above declarations should be written as:
+<PRE>
+    class Base
+    {
+    public:
+        void Read(wxFile& file);
+        void Read(const wxString& filename);
+
+    protected:
+        virtual void DoRead(wxFile& file);
+    };
+
+    class Derived : public Base
+    {
+    protected:
+        virtual void DoRead(wxFile& file) { ... }
+    };
+</PRE>
+
+This technique is widely used in many of wxWindows classes - for example,
+<TT>wxWindow</TT> has more than a dozen of <TT>DoXXX()</TT> functions which
+allows to have many overloaded versions of commonly used methods such as
+<TT>SetSize()</TT>
+
     <P><LI><A NAME="no_extra_semicolon"></A><B>Don't use extra semi-colons on top level</B></LI><P>
 Some compilers don't pay any attention to extra semicolons on top level, as in
 <PRE>
@@ -515,6 +577,13 @@ While DOS/Windows compilers don't seem to mind, their Unix counterparts don't
 like files without terminating new-line. Such files also give a warning message
 when loaded to vim (the Unix programmer's editor of choice :-)), so please think
 about terminating the last line.
+
+    <P><LI><A NAME="no_case_only_diff"></A><B>Avoid globals differing by case only</B></LI><P>
+The linker on VMS is case-insensitive. Therefore all external variables and
+functions which differ only in case are not recognized by the linker as
+different, so all externals should differ in more than the case only:
+i.e. <TT>GetId</TT> is the same as <TT><GetID</TT>. 
+
   </OL>
 
   <BR>