Added possibility of 2-step initialisation, and wxWIZARD_EX_HELPBUTTON style.

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

diff --git a/docs/html/standard.htm b/docs/html/standard.htm
index 15ee6ef10632611ae85dd26baf9b2d63e1c8ce0b..196b63ff5a6a949d0e413d539a54c4e73361768a 100644 (file)
--- a/docs/html/standard.htm
+++ b/docs/html/standard.htm
@@ -9,10 +9,10 @@
 
 <font face="Arial, Lucida Sans, Helvetica">
 
 
 <font face="Arial, Lucida Sans, Helvetica">
 

-<table width=100% border=4 cellpadding=5 cellspacing=0>
+<table width=100% border=0 cellpadding=5 cellspacing=0>

 <tr>
 <tr>

-<td bgcolor="#660000">
-<font size=+1 face="Arial, Lucida Sans, Helvetica" color="#FFFFFF">
+<td bgcolor="#C4ECF9">
+<font size=+1 face="Arial, Lucida Sans, Helvetica" color="#000000">

 wxWindows Programmer Style Guide
 </font>
 </td>
 wxWindows Programmer Style Guide
 </font>
 </td>


@@ -50,11 +50,19 @@ C++ portability guide</A> by David Williams.
     <LI><A HREF="#no_stl">Don't use STL</A></LI>
     <LI><A HREF="#no_fordecl">Don't declare variables inside <TT>for()</TT></A></LI>
     <LI><A HREF="#no_nestedclasses">Don't use nested classes</A></LI>
     <LI><A HREF="#no_stl">Don't use STL</A></LI>
     <LI><A HREF="#no_fordecl">Don't declare variables inside <TT>for()</TT></A></LI>
     <LI><A HREF="#no_nestedclasses">Don't use nested classes</A></LI>

+    <LI><A HREF="#no_newlogicalops">Don't use new logical operators keywords</A></LI>
+  </OL>
+  <BR>
+  <LI>Other compiler limitations</LI>
+  <OL>

     <LI><A HREF="#no_ternarywithobjects">Use ternary operator ?: carefully</A></LI>
     <LI><A HREF="#no_ternarywithobjects">Use ternary operator ?: carefully</A></LI>

+    <LI><A HREF="#no_autoaggregate">Don't use initializers with automatic arrays</A></LI>
+    <LI><A HREF="#no_dtorswithoutctor">Always have at least one constructor in a class with destructor</A></LI>

   </OL>
   <BR>
   <LI>General recommendations</LI>
   <OL>
   </OL>
   <BR>
   <LI>General recommendations</LI>
   <OL>

+    <LI><A HREF="#no_cppcommentsinc">No C++ comments in C code></A></LI>

     <LI><A HREF="#no_globals">No global variables with constructor</A></LI>
     <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_globals">No global variables with constructor</A></LI>
     <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>


@@ -71,6 +79,7 @@ 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_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>
   <BR>
   <LI>Style choices</LI>


@@ -104,8 +113,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>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>
     <LI><A HREF="#set_get">Use Set/Get prefixes for accessors</A></LI>
     <LI><A HREF="#constants">wxNAMING_CONSTANTS</A></LI>
   </OL>


@@ -263,30 +271,34 @@ The scope of a variable declared inside <TT>for()</TT> statement changed several
 years ago, however many compilers still will complain about second declaration
 of <TT>i</TT> in the following code:
 <PRE>
 years ago, however many compilers still will complain about second declaration
 of <TT>i</TT> in the following code:
 <PRE>

-  for ( int i = 0; i < 10; i++ ) {
+  for ( int i = 0; i &lt; 10; i++ ) {

     ...
   }
 
   ...
 
     ...
   }
 
   ...
 

-  for ( int i = 0; i < 10; i++ ) {
+  for ( int i = 0; i &lt; 10; i++ ) {

     ...
   }
 </PRE>
     ...
   }
 </PRE>

-Even if it's perfectly legal now.
+even though if it's perfectly legal now.

 <P><U>Workaround</U>: write this instead:
 <PRE>
   int i;
 <P><U>Workaround</U>: write this instead:
 <PRE>
   int i;

-  for ( i = 0; i < 10; i++ ) {
+  for ( i = 0; i &lt; 10; i++ ) {

     ...
   }
 
   ...
 
     ...
   }
 
   ...
 

-  for ( i = 0; i < 10; i++ ) {
+  for ( i = 0; i &lt; 10; i++ ) {

     ...
   }
 </PRE>
     ...
   }
 </PRE>

+or, even better, use different names for the variables in the different for
+loops (in particular, avoid mute variable names like <tt>i<tt> above) - then
+you can declare them in the loop statement and don't pollute the outer name
+space with local loop variables.

 
   <P><LI><A NAME="no_nestedclasses"></A><B>Don't use nested classes</B></LI><P>
 Nested classes are, without doubt, a very good thing because they allow to hide
 
   <P><LI><A NAME="no_nestedclasses"></A><B>Don't use nested classes</B></LI><P>
 Nested classes are, without doubt, a very good thing because they allow to hide


@@ -332,28 +344,73 @@ you can try the following:
 including the header if you change the PrivateLibClass declaration (it's
 an example of a more general interface/implementation separation idea).
 
 including the header if you change the PrivateLibClass declaration (it's
 an example of a more general interface/implementation separation idea).
 

+<P><LI><A NAME="no_newlogicalops"></A><B>Don't use new logical operators keywords</B></LI><P>
+The C++ standard has introduced the following new reserved words: <tt>or</tt>,
+<tt>and</tt>, <tt>not</tt>, <tt>xor</tt>, <tt>bitand</tt>, <tt>bitor</tt>,
+<tt>compl</tt>, <tt>and_eq</tt>, <tt>or_eq</tt>, <tt>not_eq</tt>,
+<tt>or_eq</tt> which can be used instead of the usual C operations &#38;&#38;,
+&#124;&#124;, &#126; etc.
+<P>This wonderful (and not backwards compatible in addition to being
+absolutely useless) new feature means that these new keywords should not be
+used as the variable names - even if current compilers usually will accept
+this, your code will break in the future. For most of the keywords, using them
+as variable names is quite unlikely, but <tt>or</tt> and <tt>compl</tt> were
+used in the wxWindows sources which seems to indicate that they are the most
+likely candidates.
+<P>It goes without saying that these new keywords should not be used instead
+of the tradional C operators neither both because most compilers don't accept
+them and because using them in C code makes it less readable.
+</OL>
+
+  <BR>
+  <LI>Other compiler limitations</LI><P>
+This section lists the less obvious limitations of the current C++ compilers
+which are less restrictive than the ones mentioned in the previous section but
+are may be even more dangerous as a program which compiles perfectly well on
+some platform and seems to use only standard C++ featurs may still fail to
+compile on another platform and/or with another compiler.
+
+<OL>

   <P><LI><A NAME="no_ternarywithobjects"></A><B>Use ternary operator ?: carefully</B></LI><P>
   The ternary operator <TT>?:</TT> shouldn't be used with objects (i.e. if any
   <P><LI><A NAME="no_ternarywithobjects"></A><B>Use ternary operator ?: carefully</B></LI><P>
   The ternary operator <TT>?:</TT> shouldn't be used with objects (i.e. if any

-of its operands are objects) because some compilers (notable Borland C++) fail
+of its operands are objects) because some compilers (notably Borland C++) fail

 to compile such code.
 <P><U>Workaround</U>: use <TT>if/else</TT> instead.
 <PRE>
     wxString s1, s2;
 
     // Borland C++ won't compile the line below
 to compile such code.
 <P><U>Workaround</U>: use <TT>if/else</TT> instead.
 <PRE>
     wxString s1, s2;
 
     // Borland C++ won't compile the line below

-    wxString s = s1.Len() < s2.Len() ? s1 : s2;
+    wxString s = s1.Len() &lt; s2.Len() ? s1 : s2;

 
     // but any C++ compiler will compile this
     wxString s;
 
     // but any C++ compiler will compile this
     wxString s;

-    if ( s1.Len() < s2.Len() )
+    if ( s1.Len() &lt; s2.Len() )

         s = s1;
     else
         s = s2;
 </PRE>
         s = s1;
     else
         s = s2;
 </PRE>

+
+   <P><LI><A NAME="no_autoaggregate"></A><B>Don't use initializers with automatic arrays</B></LI><P>
+The initializers for automatic array variables are not supported by some older
+compilers. For example, the following line
+<PRE>
+    int daysInMonth[12] = { 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 };
+</PRE>
+will fail to compile with HP-UX C++ compiler.
+<P><U>Workaround</U>: either make the array static or initialize each item
+separately: in the (stupid) example above, the array should be definitely
+declared as <TT>static const</TT> (assuming that the leap years are dealt with
+elsewhere somehow...) which is ok. When an array is really not const, you
+should initialize each element separately.
+
+   <P><LI><A NAME="no_dtorswithoutctor"></A><B>Always have at least one constructor in a class with destructor</B></LI><P>
+It is a good rule to follow in general, but some compilers (HP-UX) enforce it.
+So even if you are sure that the default constructor for your class is ok but
+it has a destructor, remember to add an empty default constructor to it.

 </OL>
 
   <BR>
 </OL>
 
   <BR>

-  <LI>General recommendations</B></LI><P>
+  <LI>General recommendations</LI><P>

 While the recommendations in the previous section may not apply to you if you're
 only working with perfect compilers which implement the very newest directives of
 C++ standard, this section contains compiler- (and language-) independent advice
 While the recommendations in the previous section may not apply to you if you're
 only working with perfect compilers which implement the very newest directives of
 C++ standard, this section contains compiler- (and language-) independent advice


@@ -361,6 +418,18 @@ which <B>must</B> be followed if you wish to write correct, i.e. working, progra
 also contains some C/C++ specific remarks in the end which are less
 important.
   <OL>
 also contains some C/C++ specific remarks in the end which are less
 important.
   <OL>

+    <P><LI><A NAME="no_cppcommentsinc"><B>No C++ comments in C code></B></LI><P>
+Never use C++ comments in C code - not all C compilers/preprocessors
+understand them. Although we're mainly concerned with C++ here, there are
+several files in wxWindows sources tree which are compiled with C compiler.
+Among them are <TT>include/wx/setup.h</TT> and <TT>include/wx/expr.h</TT>.
+
+Another thing related to C vs C++ preprocessor differences is that some old C
+preprocessors require that all directives start in the first column (while
+it's generally allowed to have any amount of whitespace before them in C++),
+so you should start them in the beginning of the line in files which are
+compiled with C compiler.
+

     <P><LI><A NAME="no_globals"></A><B>No global variables with constructors</B></LI><P>
 In C++, the constructors of global variables are called before the
 <TT>main()</TT> function (or <TT>WinMain()</TT> or any other program entry point)
     <P><LI><A NAME="no_globals"></A><B>No global variables with constructors</B></LI><P>
 In C++, the constructors of global variables are called before the
 <TT>main()</TT> function (or <TT>WinMain()</TT> or any other program entry point)


@@ -538,7 +607,7 @@ put another one after it.
   </OL>
 
   <BR>
   </OL>
 
   <BR>

-  <LI>Unix/DOS differences</B></LI><P>
+  <LI>Unix/DOS differences</LI><P>

   Two operating systems supported by wxWindows right now are (different flavours
 of) Unix and Windows 3.1/95/NT (although Mac, OS/2 and other ports exist/are
 being developed as well). The main differences between them are summarized
   Two operating systems supported by wxWindows right now are (different flavours
 of) Unix and Windows 3.1/95/NT (although Mac, OS/2 and other ports exist/are
 being developed as well). The main differences between them are summarized


@@ -577,21 +646,29 @@ 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.
 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>
   </OL>
 
   <BR>

-  <LI>Style choices</B></LI><P>
+  <LI>Style choices</LI><P>

   All wxWindows specific style guidelines are specified in the next
 section, here are the choices which are not completely arbitrary,
 but have some deeper and not wxWindows-specific meaning.
 
   <OL>
     <P><LI><A NAME="naming_conv"></A><B>Naming conventions: use <TT>m_</TT> for members</B></LI><P>
   All wxWindows specific style guidelines are specified in the next
 section, here are the choices which are not completely arbitrary,
 but have some deeper and not wxWindows-specific meaning.
 
   <OL>
     <P><LI><A NAME="naming_conv"></A><B>Naming conventions: use <TT>m_</TT> for members</B></LI><P>

-It's extremely important to write readable code. One of the first steps in this
-direction is the choice of naming convention. It may be quite vague or strictly
-define the names of all the variables and function in the program, however it
-surely must somehow allow the reader to distinguish between variable and
-functions and local variables and member variables from the first glance.
+We all know how important it is to write readable code. One of the first steps
+in this direction is the choice of naming convention. It may be quite vague or
+strictly define the names of all the variables and function in the program,
+however it surely must somehow allow the reader to distinguish between
+variable and functions and local variables and member variables from the first
+glance.

 <P>The first requirement is commonly respected, but for some strange reasons, the
 second isn't, even if it's much more important because, after all, the immediate
 context usually allows you to distinguish a variable from a function in
 <P>The first requirement is commonly respected, but for some strange reasons, the
 second isn't, even if it's much more important because, after all, the immediate
 context usually allows you to distinguish a variable from a function in


@@ -710,8 +787,8 @@ the right header for given platform. Any new headers should conform to this
 setup as well to allow including <TT>&lt;wx/foo.h&gt;</TT> on any platform.<P>
 
 Note that wxWindows implementation files should use quotes when including wxWindows
 setup as well to allow including <TT>&lt;wx/foo.h&gt;</TT> on any platform.<P>
 
 Note that wxWindows implementation files should use quotes when including wxWindows

-headers, not angled brackets. Applications should use angled brackets. There
-is a reason for it (can anyone remember what this is?).
+headers, not angled brackets. Applications should use angled brackets. This
+ensures that the dependencies are correctly handled by the compiler.

 
     <P><LI><A NAME="include_guards"></LI><B>Include guards</B><P>
 To minimize the compile time C++ programmers often use so called include
 
     <P><LI><A NAME="include_guards"></LI><B>Include guards</B><P>
 To minimize the compile time C++ programmers often use so called include


@@ -815,12 +892,6 @@ WXDLLEXPORT_DATA(extern wxApp*) wxTheApp;
 The reason for the strange syntax for data is that some compilers use different
 keyword ordering for exporting data.
 
 The reason for the strange syntax for data is that some compilers use different
 keyword ordering for exporting data.
 

-<P>There also several other places where you should take care of shared
-library case: all IMPLEMENT_xxx macros which are usually used in the
-corresponding .cpp files must be taken inside
-"<TT>&#35;if !USE_SHARED_LIBRARY</TT>" and in the <TT>&#35;if USE_SHARED_LIBRARY</TT>
-case you should put them inside <TT>common/cmndata.cpp</TT> file.
-

     <P><LI><A NAME="set_get"></LI><B>Use Set/Get prefixes for accessors</B><P>
 There is a convention in wxWindows to prefix the accessors (i.e. any simple, in
 general, inline function which does nothing else except changing or returning
     <P><LI><A NAME="set_get"></LI><B>Use Set/Get prefixes for accessors</B><P>
 There is a convention in wxWindows to prefix the accessors (i.e. any simple, in
 general, inline function which does nothing else except changing or returning