docs/html/standard.htm

   1 <HTML>
   2 <HEAD>
   3   <TITLE>wxWindows Programmer Style Guide</TITLE>
   4 </HEAD>
   5
   6 <BODY>
   7
   8 <a name="top"></a>
   9
  10 <font face="Arial, Lucida Sans, Helvetica">
  11
  12 <table width=100% border=4 cellpadding=5 cellspacing=0>
  13 <tr>
  14 <td bgcolor="#660000">
  15 <font size=+1 face="Arial, Lucida Sans, Helvetica" color="#FFFFFF">
  16 wxWindows Programmer Style Guide
  17 </font>
  18 </td>
  19 </tr>
  20 </table>
  21
  22 <P>
  23
  24 by <A HREF=mailto:zeitlin@dptmaths.ens-cachan.fr>Vadim Zeitlin</A><P>
  25
  26 This guide is intended for people who are (or intending to start) writing code
  27 for <A HREF="http://www.wxwindows.org" target=_top>wxWindows</A> class library.
  28
  29 <P>
  30 The guide is separated into two parts: the first one addresses the general
  31 compatibility issues and is not wxWindows-specific. The advises in this part
  32 will hopefully help you to write programs which compile and run on greater
  33 variety of platforms. The second part details the wxWindows code organization and
  34 its goal it to make wxWindows as uniform as possible without imposing too
  35 many restrictions on the programmer.
  36 <P>
  37 Acknowledgements: This guide is partly based on <A
  38 HREF="http://www.mozilla.org/hacking/portable-cpp.html" target=_top>
  39 C++ portability guide</A> by David Williams.
  40
  41 <P>
  42 <H3>General C++ Rules</H3>
  43 <UL>
  44   <LI>New or not widely supported C++ features</LI>
  45   <OL>
  46     <LI><A HREF="#no_templates">Don't use C++ templates</A></LI>
  47     <LI><A HREF="#no_exceptions">Don't use C++ exceptions</A></LI>
  48     <LI><A HREF="#no_rtti">Don't use RTTI</A></LI>
  49     <LI><A HREF="#no_namespaces">Don't use namespaces</A></LI>
  50     <LI><A HREF="#no_stl">Don't use STL</A></LI>
  51     <LI><A HREF="#no_fordecl">Don't declare variables inside <TT>for()</TT></A></LI>
  52     <LI><A HREF="#no_nestedclasses">Don't use nested classes</A></LI>
  53   </OL>
  54   <BR>
  55   <LI>Other compiler limitations</LI>
  56   <OL>
  57     <LI><A HREF="#no_ternarywithobjects">Use ternary operator ?: carefully</A></LI>
  58     <LI><A HREF="#no_autoaggregate">Don't use initializers with automatic arrays</A></LI>
  59     <LI><A HREF="#no_dtorswithoutctor">Always have at least one constructor in a class with destructor</A></LI>
  60   </OL>
  61   <BR>
  62   <LI>General recommendations</LI>
  63   <OL>
  64     <LI><A HREF="#no_cppcommentsinc">No C++ comments in C code></A></LI>
  65     <LI><A HREF="#no_globals">No global variables with constructor</A></LI>
  66     <LI><A HREF="#no_warnings">Turn on all warnings and eradicate them</A></LI>
  67     <LI><A HREF="#no_assume_sizeof">Don't rely on <TT>sizeof(int) == 2</TT>...</A></LI>
  68     <LI><A HREF="#no_assignment_in_if">No assignments in conditional expressions</A></LI>
  69     <LI><A HREF="#no_comment_code">Use <TT>#if 0</TT> rather than comments to temporarily disable blocks of code</A></LI>
  70     <LI><A HREF="#no_overloaded_virtuals">Avoid overloaded virtual functions</A></LI>
  71     <LI><A HREF="#no_extra_semicolon">Don't use extra semi-colons on top level</A></LI>
  72   </OL>
  73   <BR>
  74   <LI>Unix/DOS differences</LI>
  75   <OL>
  76     <LI><A HREF="#use_cpp_ext">Use .cpp for C++ source file extension</A></LI>
  77     <LI><A HREF="#no_backslash">Don't use backslash ('\\') in &#35;includes</A></LI>
  78     <LI><A HREF="#no_carriagereturn">Avoid carriage returns in cross-platform code</A></LI>
  79     <LI><A HREF="#no_caps_in_filenames">Use only lower letter filenames</A></LI>
  80     <LI><A HREF="#no_incomplete_files">Terminate the files with a new-line</A></LI>
  81     <LI><A HREF="#no_case_only_diff">Avoid globals differing by case only</A></LI>
  82   </OL>
  83   <BR>
  84   <LI>Style choices</LI>
  85   <OL>
  86     <LI><A HREF="#naming_conv">Naming conventions: use <TT>m_</TT> for members</A></LI>
  87     <LI><A HREF="#no_void_param">Don't use <TT>void</TT> for functions without arguments</A></LI>
  88     <LI><A HREF="#no_const_int">Don't use <TT>const</TT> for non pointer/reference arguments</A></LI>
  89   </OL>
  90 </UL>
  91
  92 <P>
  93
  94 <H3>wxWindows Rules</H3>
  95 <UL>
  96   <LI>Files location and naming conventions</LI>
  97   <OL>
  98     <LI><A HREF="#file_locations">File locations</A></LI>
  99     <LI><A HREF="#include_guards">Include guards</A></LI>
 100     <LI><A HREF="#pch">Precompiled headers</A></LI>
 101   </OL>
 102
 103   <BR>
 104   <LI>File layout and indentation</LI>
 105   <OL>
 106     <LI><A HREF="#wxwin_header">wxWindows standard header</A></LI>
 107     <LI><A HREF="#indentation">Indent your code with 4 spaces (no tabs!)</A></LI>
 108     <LI><A HREF="#class_decl">Order of parts in a class declarations</A></LI>
 109   </OL>
 110
 111   <BR>
 112   <LI>More about naming conventions</LI>
 113   <OL>
 114     <LI><A HREF="#wx_prefix">Use wx or WX prefix for all public symbols</A></LI>
 115     <LI><A HREF="#wxdllexport">Use WXDLLEXPORT with all classes/functions in wxMSW/common code</A></LI>
 116     <LI><A HREF="#set_get">Use Set/Get prefixes for accessors</A></LI>
 117     <LI><A HREF="#constants">wxNAMING_CONSTANTS</A></LI>
 118   </OL>
 119
 120   <BR>
 121   <LI>Miscellaneous</LI>
 122   <OL>
 123     <LI><A HREF="#forward_decl">Use forward declarations whenever possible</A></LI>
 124     <LI><A HREF="#debug_macros">Use debugging macros</A></LI>
 125   </OL>
 126 </UL>
 127
 128 <HR>
 129
 130 <H3>General C++ Rules</H3>
 131 <UL>
 132   <LI>New or not widely supported C++ features</LI>
 133
 134   <P>The usage of all features in this section is not recommended for one reason: they appeared in C++ relatively recently and are not yet
 135 supported by all compilers. Moreover, when they're supported, there are
 136 differences between different vendor's implementations. It's understandable that
 137 you might love one (or all) of these features, but you surely can write C++
 138 programs without them. Where possible, workarounds to compensate for absence
 139 of your favourite C++ abilities are indicated.
 140   <P>Just to suppress any doubts that there are compilers which don't support
 141 these new features, you can think about Win16 (a.k.a. Win 3.1) compilers,
 142 <I>none</I> of which supports <I>any</I> feature from the list below.
 143
 144   <OL>
 145     <P><LI><A NAME="no_templates"></A><B>Don't use C++ templates</B></LI><P>
 146 Besides the reasons mentioned above, template usage also makes the
 147 program compile much slower (200%-300% is not uncommon) and their support
 148 even in the compilers which have had it for a long time is far from perfect
 149 (the best example is probably gcc).
 150 <P><U>Workaround</U>: The things you would like to use templates for are,
 151 most commonly, polymorphic containers (in the sense that they can contain objects of
 152 any type without compromising C++ type system, i.e. using <TT>void *</TT>
 153 is out of question). wxWindows provides <A HREF="TODO">dynamic
 154 arrays and lists</A> which are sufficient in 99% of cases - please don't hesitate
 155 to use them. Lack of template is not a reason to use static arrays or
 156 type-less (passing by <TT>void *</TT>) containers.
 157
 158     <P><LI><A NAME="no_exceptions"></A><B>Don't use C++ exceptions</B></LI><P>
 159 The C++ exception system is an error-reporting mechanism. Another reasons not to use it,
 160 besides portability, are the performance penalty it imposes (small, but, at least for
 161 current compilers, non-zero), and subtle problems with
 162 memory/resource deallocation it may create (the place where you'd like to use
 163 C++ exceptions most of all are the constructors, but you need to be very
 164 careful in order to be able to do it).
 165 <P><U>Workaround</U>: there is no real workaround, of course, or the exceptions
 166 wouldn't have been added to the language. However, there are several rules which
 167 might help here:<P>
 168
 169 <OL>
 170   <LI>Every function returns an integer (or at least boolean) error code.
 171       <P>There is no such thing as a function that never fails - even if it can't
 172       fail now, it might do it later, when modified to be more powerful/general.
 173       Put the <TT>int</TT> or <TT>bool</TT> return type from the very beginning!<P>
 174   </LI><LI>Every function you call may fail - check the return code!
 175       <P>Never rely on the function's success, always test for a possible error.<P>
 176   </LI><LI>Tell the user about the error, don't silently ignore them.
 177       <P>Exceptions are always caught and, normally, processed when they're
 178       caught. In the same manner, the error return code must always be processed
 179       somehow. You may choose to ignore it, but at least tell the user that
 180       something wrong happened using <A HREF="TODO"><TT>wxLogError</TT></A> or
 181       <A HREF="TODO"><TT>wxLogWarning</TT></A> functions. All wxWindows
 182       functions (must) log the error messages on failure - this can be disabled
 183       by using <A HREF="TODO">wxLogNull</A> object before calling it.
 184       <P>Examples:<UL>
 185         <LI><I>Wrong</I>:
 186         <PRE>
 187 void ReadAddressBookFile(const wxString& strName)
 188 {
 189   wxFile file;
 190
 191   if ( !file.Open(strFile) )
 192     return;
 193
 194   ...process it...
 195 }
 196         </PRE>
 197         </LI><LI><I>Correct</I>:
 198         <PRE>
 199 // returns false if the address book couldn't be read
 200 bool ReadAddressBookFile(const wxString& strName)
 201 {
 202   wxFile file;
 203
 204   if ( !file.Open(strFile) ) {
 205     // wxFile logged an error because file couldn't be opened which
 206     // contains the system error code, however it doesn't know what
 207     // this file is for and an error message "can't open $GLCW.ADB"
 208     // can be quite confusing for the user. Here we say what we mean.
 209     wxLogError("Can't read address book from '%s'!",
 210                strName.c_str());
 211     return false;
 212   }
 213
 214   ...process it...
 215
 216   return true;
 217 }
 218         </PRE>
 219         or, if it's not an error if file doesn't exist (here we could just check
 220         its existence, but let's suppose that there is no <TT>wxFile::Exists()</TT>)
 221         we can also write:
 222         <PRE>
 223 // returns false if address book file doesn't exist
 224 bool ReadAddressBookFile(const wxString& strName)
 225 {
 226   wxFile file;
 227
 228   // start a block inside which all log messages are suppressed
 229   {
 230     wxLogNull noLog;
 231     if ( !file.Open(strFile) )
 232       return false;
 233   }
 234
 235   ...process it...
 236
 237   return true;
 238 }
 239         </PRE></LI>
 240     </UL>
 241   </OL>
 242
 243     <P><LI><A NAME="no_rtti"></A><B>Don't use RTTI</B></LI><P>
 244 RTTI stands for Run-Time Type Information and there is probably no other
 245 reason not to use it except the portability issue and the fact that it adds
 246 <TT>sizeof(void *)</TT> bytes to any class having virtual functions (at least,
 247 in the implementations I'm aware of).
 248 <P><U>Workaround</U>: use wxWindows RTTI system which allows you to do almost
 249 everything which the new C++ RTTI, except that, of course, you have to use
 250 macros instead of the (horrible looking, BTW) <TT>dynamic_cast</TT>.
 251
 252     <P><LI><A NAME="no_namespaces"></A><B>Don't use namespaces</B></LI><P>
 253 This topic is subject to change with time, however for the moment all wxWindows
 254 classes/functions live in the global namespace.
 255 <P><U>Workaround</U>: None.
 256
 257     <P><LI><A NAME="no_stl"></A><B>Don't use STL</B></LI><P>
 258 STL is the new C++ standard library, proposing all kinds of template containers
 259 and generic algorithm implementations. Templates are the heart (and almost
 260 everything else) of the library, so its usage is out of question. Besides, even
 261 with the compilers which do support templates, STL has many of its own problems,
 262 there are many "not 100% standard compatible" vendor implementations, none of existing debuggers understands its
 263 complicated data structures, ... the list can go on (almost) forever.
 264 <P><U>Workaround</U>: Use wxString, dynamic arrays and lists and other wxWindows
 265 classes. wxString has many of the most often used functions of std::string STL
 266 class (typedef to be precise).
 267     <P><LI><A NAME="no_fordecl"></A><B>Don't declare variables inside <TT>for()
 268                                        </TT></B></LI><P>
 269 The scope of a variable declared inside <TT>for()</TT> statement changed several
 270 years ago, however many compilers still will complain about second declaration
 271 of <TT>i</TT> in the following code:
 272 <PRE>
 273   for ( int i = 0; i < 10; i++ ) {
 274     ...
 275   }
 276
 277   ...
 278
 279   for ( int i = 0; i < 10; i++ ) {
 280     ...
 281   }
 282 </PRE>
 283 Even if it's perfectly legal now.
 284 <P><U>Workaround</U>: write this instead:
 285 <PRE>
 286   int i;
 287   for ( i = 0; i < 10; i++ ) {
 288     ...
 289   }
 290
 291   ...
 292
 293   for ( i = 0; i < 10; i++ ) {
 294     ...
 295   }
 296 </PRE>
 297
 298   <P><LI><A NAME="no_nestedclasses"></A><B>Don't use nested classes</B></LI><P>
 299 Nested classes are, without doubt, a very good thing because they allow to hide
 300 "private" (in the sense that they're used only inside the library) classes and,
 301 generally, put the related things together.
 302 <P>Unfortunately, some compilers have trouble understanding them, so we must
 303 sacrifice the ideals of software design to get a working program in this case.
 304 <P><U>Workaround</U>: instead of
 305 <PRE>
 306   // in the header
 307   class PublicLibClass {
 308   ...
 309   private:
 310     class PrivateLibClass { ... } m_object;
 311   };
 312 </PRE>
 313 you can try the following:
 314 <PRE>
 315   // in the header
 316   class PrivateLibClass; // fwd decl
 317   class PublicLibClass {
 318   ...
 319   private:
 320    class PrivateLibClass *m_pObject;
 321   };
 322
 323   // in the .cpp file
 324   class PrivateLibClass { ... };
 325
 326   PublicLibClass::PublicLibClass()
 327   {
 328     m_pObject = new PrivateLibClass;
 329
 330     ...
 331   }
 332
 333   PublicLibClass::~PublicLibClass()
 334   {
 335     delete m_pObject;
 336   }
 337 </PRE>
 338 <P>A nice side effect is that you don't need to recompile all the files
 339 including the header if you change the PrivateLibClass declaration (it's
 340 an example of a more general interface/implementation separation idea).
 341 </OL>
 342
 343   <BR>
 344   <LI>Other compiler limitations</B></LI><P>
 345 This section lists the less obvious limitations of the current C++ compilers
 346 which are less restrictive than the ones mentioned in the previous section but
 347 are may be even more dangerous as a program which compiles perfectly well on
 348 some platform and seems to use only standard C++ featurs may still fail to
 349 compile on another platform and/or with another compiler.
 350
 351 <OL>
 352   <P><LI><A NAME="no_ternarywithobjects"></A><B>Use ternary operator ?: carefully</B></LI><P>
 353   The ternary operator <TT>?:</TT> shouldn't be used with objects (i.e. if any
 354 of its operands are objects) because some compilers (notable Borland C++) fail
 355 to compile such code.
 356 <P><U>Workaround</U>: use <TT>if/else</TT> instead.
 357 <PRE>
 358     wxString s1, s2;
 359
 360     // Borland C++ won't compile the line below
 361     wxString s = s1.Len() < s2.Len() ? s1 : s2;
 362
 363     // but any C++ compiler will compile this
 364     wxString s;
 365     if ( s1.Len() < s2.Len() )
 366         s = s1;
 367     else
 368         s = s2;
 369 </PRE>
 370
 371    <P><LI><A NAME="no_autoaggregate"></A><B>Don't use initializers with automatic arrays</B></LI><P>
 372 The initializers for automatic array variables are not supported by some older
 373 compilers. For example, the following line
 374 <PRE>
 375     int daysInMonth[12] = { 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 };
 376 </PRE>
 377 will fail to compile with HP-UX C++ compiler.
 378 <P><U>Workaround</U>: either make the array static or initialize each item
 379 separately: in the (stupid) example above, the array should be definitely
 380 declared as <TT>static const</TT> (assuming that the leap years are dealt with
 381 elsewhere somehow...) which is ok. When an array is really not const, you
 382 should initialize each element separately.
 383
 384    <P><LI><A NAME="no_dtorswithoutctor"></A><B>Always have at least one constructor in a class with destructor</B></LI><P>
 385 It is a good rule to follow in general, but some compilers (HP-UX) enforce it.
 386 So even if you are sure that the default constructor for your class is ok but
 387 it has a destructor, remember to add an empty default constructor to it.
 388 </OL>
 389
 390   <BR>
 391   <LI>General recommendations</B></LI><P>
 392 While the recommendations in the previous section may not apply to you if you're
 393 only working with perfect compilers which implement the very newest directives of
 394 C++ standard, this section contains compiler- (and language-) independent advice
 395 which <B>must</B> be followed if you wish to write correct, i.e. working, programs. It
 396 also contains some C/C++ specific remarks in the end which are less
 397 important.
 398   <OL>
 399     <P><LI><A NAME="no_cppcommentsinc"><B>No C++ comments in C code></B></LI><P>
 400 Never use C++ comments in C code - not all C compilers/preprocessors
 401 understand them. Although we're mainly concerned with C++ here, there are
 402 several files in wxWindows sources tree which are compiled with C compiler.
 403 Among them are <TT>include/wx/setup.h</TT> and <TT>include/wx/expr.h</TT>.
 404
 405 Another thing related to C vs C++ preprocessor differences is that some old C
 406 preprocessors require that all directives start in the first column (while
 407 it's generally allowed to have any amount of whitespace before them in C++),
 408 so you should start them in the beginning of the line in files which are
 409 compiled with C compiler.
 410
 411     <P><LI><A NAME="no_globals"></A><B>No global variables with constructors</B></LI><P>
 412 In C++, the constructors of global variables are called before the
 413 <TT>main()</TT> function (or <TT>WinMain()</TT> or any other program entry point)
 414 starts executing. Thus, there is no possibility to initialize <I>anything</I>
 415 before the constructor call. The order of construction is largely
 416 implementation-defined, meaning that there is no guarantee that one global
 417 object will be initialized before another one (except if they are both defined
 418 in the same translation unit, i.e. .cpp file). Most importantly, no custom
 419 memory allocation operators are installed at the moment of execution of global
 420 variables constructors, so a (less restrictive) rule is that you should have
 421 no global variables which allocate memory (or do anything else non-trivial) in
 422 the constructor. Of course, if an object doesn't allocate memory in its constructor
 423 right now, it may start making it later, so you can only be sure about this if
 424 you don't use <I>any</I> variables of object (as opposed to simple:
 425 <TT>int</TT>, ...) types. Example: currently, wxString doesn't allocate memory
 426 in its default constructor, so you might think that having a global (initially)
 427 empty wxString is safe. However, if wxString starts allocating some minimal
 428 amount of memory in its default constructor (which doesn't look unreasonable),
 429 you would have all kinds of problems with <TT>new</TT>
 430 and <TT>delete</TT> operators (overloaded in wxWindows), especially because the first <TT>new</TT> called
 431 is the standard one (before wxWindows overloads them) and <TT>delete</TT> will
 432 be the overloaded operator.
 433
 434     <P><LI><A NAME="no_warnings"></A><B>Turn on all warnings and eradicate them</B></LI><P>
 435 Give the compiler a chance to help you - turn on all warnings! You should always
 436 use the maximum available warning level of your compiler and understand and
 437 correct each of them. If, for whatever reasons, a compiler gives a warning on
 438 some perfectly legal line of code and you can't change it, please insert a
 439 comment indicating it in the code. Most oftenly, however, all compiler warnings
 440 may be avoided (not suppressed!) with minimal changes to your code.
 441
 442     <P><LI><A NAME="no_assume_sizeof"></A><B>Don't rely on <TT>sizeof(int) == 2</TT>...</B></LI><P>
 443 You should never assume any absolute constraints on data type sizes. Currently,
 444 we have 16-bit, 32-bit and 64-bit machines and even inside each class data type
 445 sizes are different. A small table illustrates it quite well:
 446 <TABLE BORDER COLS=5 WIDTH="100%" NOSAVE >
 447 <TR>
 448   <TD>Architecture/OS</TD>
 449   <TD>sizeof(short)</TD>
 450   <TD>sizeof(int)</TD>
 451   <TD>sizeof(long)</TD>
 452   <TD>sizeof(void *)</TD>
 453 </TR>
 454
 455 <TR>
 456   <TD>i386/Windows 3.1</TD>
 457   <TD>2</TD>
 458   <TD>2</TD>
 459   <TD>4</TD>
 460   <TD>2 or 4</TD>
 461 </TR>
 462
 463 <TR>
 464   <TD>i386/Windows 95</TD>
 465   <TD>2</TD>
 466   <TD>4</TD>
 467   <TD>4</TD>
 468   <TD>4</TD>
 469 </TR>
 470
 471 <TR>
 472   <TD>Merced/Win64</TD>
 473   <TD>2</TD>
 474   <TD>4</TD>
 475   <TD>4</TD>
 476   <TD>8</TD>
 477 </TR>
 478
 479 <TR>
 480   <TD>Alpha/Linux</TD>
 481   <TD>???</TD>
 482   <TD>???</TD>
 483   <TD>???</TD>
 484   <TD>???</TD>
 485 </TR>
 486 </TABLE>
 487
 488     <P><LI><A NAME="no_assignment_in_if"></A><B>No assignments in conditional expressions</B></LI><P>
 489 Although close to the heart of many C programmers (I plead guilty), code like
 490 classical <TT>if ( (c = getchar()) != EOF )</TT> is bad because it prevents you
 491 from enabling "assignment in conditional expression" warning (see also
 492 <A HREF="#no_warnings">above</A>) which is helpful to detect common
 493 mistypes like <TT>if ( x = 2 )</TT> instead of <TT>if ( x == 2 )</TT>.
 494
 495     <P><LI><A NAME="no_comment_code"></A><B>Use <TT>#if 0</TT> rather than comments to temporarily
 496                     disable blocks of code</B></LI><P>
 497 If you have to temporarily disable some code, use
 498 <PRE>
 499   #if 0 // VZ: I think this code is unneeded, it probably must be removed
 500     ...
 501   #endif // 0
 502 </PRE>
 503 instead of
 504 <PRE>
 505   /*
 506     ...
 507   */
 508 </PRE>
 509 The reason is simple: if there are any <TT>/* ... */</TT> comments inside
 510 <TT>...</TT> the second version will, of course, miserably fail.
 511
 512     <P><LI><A NAME="no_overloaded_virtuals"></A><B>Avoid overloaded virtual functions</B></LI><P>
 513
 514 You should avoid having overloaded virtual methods in a base class because if
 515 any of them is overriden in a derived class, then all others must be overriden
 516 as well or it would be impossible to call them on an object of derived class.
 517
 518 For example, the following code:
 519
 520 <PRE>
 521     class Base
 522     {
 523     public:
 524         virtual void Read(wxFile& file);
 525         virtual void Read(const wxString& filename);
 526     };
 527
 528     class Derived : public Base
 529     {
 530     public:
 531         virtual void Read(wxFile& file) { ... }
 532     };
 533
 534     ...
 535
 536     Derived d;
 537     d.Read("some_filename");    // compile error here!
 538 </PRE>
 539
 540 will fail to compile because the base class function taking <TT>filename</TT>
 541 is hidden by the virtual function overriden in the derived class (this is
 542 known as [virtual] function name hiding problem in C++).
 543
 544 <P>
 545 The standard solution to this problem in wxWindows (where we have such
 546 situations quite often) is to make both <TT>Read()</TT> functions not virtual
 547 and introduce a single virtual function <TT>DoRead()</TT>. Usually, it makes
 548 sense because the function taking a filename is (again, usually) implemented
 549 in terms of the function reading from a file anyhow (but making only this
 550 functions not virtual won't solve the above problem!).
 551 <P>
 552 So, the above declarations should be written as:
 553 <PRE>
 554     class Base
 555     {
 556     public:
 557         void Read(wxFile& file);
 558         void Read(const wxString& filename);
 559
 560     protected:
 561         virtual void DoRead(wxFile& file);
 562     };
 563
 564     class Derived : public Base
 565     {
 566     protected:
 567         virtual void DoRead(wxFile& file) { ... }
 568     };
 569 </PRE>
 570
 571 This technique is widely used in many of wxWindows classes - for example,
 572 <TT>wxWindow</TT> has more than a dozen of <TT>DoXXX()</TT> functions which
 573 allows to have many overloaded versions of commonly used methods such as
 574 <TT>SetSize()</TT>
 575
 576     <P><LI><A NAME="no_extra_semicolon"></A><B>Don't use extra semi-colons on top level</B></LI><P>
 577 Some compilers don't pay any attention to extra semicolons on top level, as in
 578 <PRE>
 579   class Foo { };;
 580 </PRE>
 581 while others complain loudly about it. Of course, you would rarely put 2
 582 semicolons yourself, but it may happen if you're using a macro
 583 (<TT>IMPLEMENT_something</TT>, for example) which already has a ';' inside and
 584 put another one after it.
 585   </OL>
 586
 587   <BR>
 588   <LI>Unix/DOS differences</B></LI><P>
 589   Two operating systems supported by wxWindows right now are (different flavours
 590 of) Unix and Windows 3.1/95/NT (although Mac, OS/2 and other ports exist/are
 591 being developed as well). The main differences between them are summarized
 592 here.
 593
 594   <OL>
 595     <P><LI><A NAME="use_cpp_ext"></A><B>Use .cpp for C++ source file extension</B></LI><P>
 596 There is, unfortunately, no standard exceptions for C++ source files. Different
 597 people use .C, .cc, .cpp, .cxx, .c++ and probably several others I forgot. Some
 598 compilers don't care about extension, but there are also other ones which can't
 599 be made to compile any file with "wrong" extension. Such compilers are very
 600 common in DOS/Windows land, that's why the .cpp extension is the least likely to
 601 cause any problems - it's the standard one under DOS and will probably be
 602 accepted by any Unix compiler as well (any counter examples?). The extension
 603 for the header files is .h.
 604
 605     <P><LI><A NAME="no_backslash"></A><B>Don't use backslash ('\\') in &#35;includes</B></LI><P>
 606 Although it's too silly to mention, please don't use backslashes in
 607 <TT>&#35;include</TT> preprocessor statement. Even not all Windows compilers accept
 608 it, without speaking about all other ones.
 609
 610     <P><LI><A NAME="no_carriagereturn"></A><B>Avoid carriage returns in cross-platform code</B></LI><P>
 611 This problem will hopefully not arise at all, with CVS taking care of this
 612 stuff, however it's perhaps not useless to remember that many Unix compilers
 613 (including, but not limited to, gcc) don't accept carriage returns
 614 (= <Ctrl-M> = '\r') in C/C++ code.
 615
 616     <P><LI><A NAME="no_caps_in_filenames"></A><B>Use only lower case filenames</B></LI><P>
 617 DOS/Windows 3.1 isn't case sensitive, Windows 95/NT are case preserving, but not
 618 case sensitive. To avoid all kinds of problems with compiling under Unix (or
 619 any other fully case-sensitive OS), please use only lower case letters in the
 620 filenames.
 621
 622     <P><LI><A NAME="no_incomplete_files"></A><B>Terminate the files with a new-line</B></LI><P>
 623 While DOS/Windows compilers don't seem to mind, their Unix counterparts don't
 624 like files without terminating new-line. Such files also give a warning message
 625 when loaded to vim (the Unix programmer's editor of choice :-)), so please think
 626 about terminating the last line.
 627
 628     <P><LI><A NAME="no_case_only_diff"></A><B>Avoid globals differing by case only</B></LI><P>
 629 The linker on VMS is case-insensitive. Therefore all external variables and
 630 functions which differ only in case are not recognized by the linker as
 631 different, so all externals should differ in more than the case only:
 632 i.e. <TT>GetId</TT> is the same as <TT>GetID</TT>.
 633
 634   </OL>
 635
 636   <BR>
 637   <LI>Style choices</B></LI><P>
 638   All wxWindows specific style guidelines are specified in the next
 639 section, here are the choices which are not completely arbitrary,
 640 but have some deeper and not wxWindows-specific meaning.
 641
 642   <OL>
 643     <P><LI><A NAME="naming_conv"></A><B>Naming conventions: use <TT>m_</TT> for members</B></LI><P>
 644 It's extremely important to write readable code. One of the first steps in this
 645 direction is the choice of naming convention. It may be quite vague or strictly
 646 define the names of all the variables and function in the program, however it
 647 surely must somehow allow the reader to distinguish between variable and
 648 functions and local variables and member variables from the first glance.
 649 <P>The first requirement is commonly respected, but for some strange reasons, the
 650 second isn't, even if it's much more important because, after all, the immediate
 651 context usually allows you to distinguish a variable from a function in
 652 C/C++ code. On the other hand, you <I>cannot</I> say what <TT>x</TT> in the
 653 following code fragment is:
 654 <PRE>
 655   void Foo::Bar(int x_)
 656   {
 657     ...
 658
 659     x = x_;
 660
 661     ...
 662   }
 663 </PRE>
 664 It might be either a local variable (unluckily the function is too long so you
 665 don't see the variable declarations when you look at <TT>x = x_</TT> line), a
 666 member variable or a global variable - you have no way of knowing.
 667 <P>The wxWindows naming convention gives you, the reader of the code, much more
 668 information about <TT>x</TT>. In the code above you know that it's a local
 669 variable because:<P>
 670 <OL>
 671   <LI>global variables are always prefixed with <TT>g_</TT></LI>
 672   <LI>member variables are always prefixed with <TT>m_</TT></LI>
 673   <LI>static variables are always prefixed with <TT>s_</TT></LI>
 674 </OL>
 675 <P>Examples:
 676 <PRE>
 677   extern int g_x; // of course, 'x' is not the best name for a global...
 678
 679   void Bar()
 680   {
 681     int x;
 682   }
 683
 684   class Foo {
 685     public:
 686       void SetX(int x) { m_x = x; }
 687     private:
 688       int m_x;
 689   };
 690 </PRE>
 691 As you see, it also solves once and for all the old C++ programmer's question:
 692 how to call <TT>SetX()</TT> parameter? The answer is simple: just call it
 693 <TT>x</TT> because there is no ambiguity with <TT>Foo::m_x</TT>.
 694 <P>The prefixes can be combined to give <TT>ms_</TT> and <TT>gs_</TT> for static
 695 member (a.k.a. class) variables and static global variables.
 696 <P>The convention is, of course, completely worthless if it is not followed:
 697 nothing like being sure that <TT>x</TT> is a local variable in the code fragment
 698 above and discovering later the following lines in the header:
 699 <PRE>
 700   class Foo {
 701     ...
 702     int x;  // I don't like wxWindows naming convention
 703   };
 704 </PRE>
 705 Please do use these prefixes, they make your code much easier to read. Also
 706 please notice that it has nothing to do with the so-called <I>Hungarian notation</I>
 707 which is used in wxMSW part of wxWindows code and which encodes the <I>type</I>
 708 of the variable in its name - it is actually quite useful in C, but has little
 709 or no sense in C++.
 710
 711     <P><LI><A NAME="no_void_param"></A><B>Don't use <TT>void</TT> for functions without
 712                     arguments</B></LI><P>
 713 In ANSI C, <TT>void Foo()</TT> takes an arbitrary number of arbitrarily typed
 714 arguments (although the form <TT>void Foo(...)</TT> is preferred) and <TT>void
 715 Foo(void)</TT> doesn't take any arguments. In C++, however, the situation is
 716 different and both declarations are completely equivalent. As there is no need
 717 to write <TT>void</TT> in this situation, let's not write it - it can only be
 718 confusing and create an impression that it really means something when it's not
 719 at all the case.
 720
 721     <P><LI><A NAME="no_const_int"></A><B>Don't use <TT>const</TT> for non pointer/reference
 722                     arguments</B></LI><P>
 723 In both C and C++ an argument passed by value cannot be modified - or, more
 724 precisely, if it is modified in the called function, only the local copy is
 725 really changed, not the caller's variable. So, semantically speaking, there is
 726 no difference between <TT>void Foo(int)</TT> and <TT>void Foo(const int)</TT>.
 727 However, the <TT>const</TT> keyword is confusing here, adds nothing to the code
 728 and even cannot be removed if <TT>Foo()</TT> is virtual and overridden (because
 729 the names are mangled differently). So, <I>for arguments passed by value</I>
 730 you shouldn't use <TT>const</TT>.
 731 <P>Of course, it doesn't apply to functions such as
 732 <TT>void PrintMessage(const char *text)</TT> where <TT>const</TT> is mandatory.
 733   </OL>
 734 </UL>
 735
 736 <P>
 737
 738 <H3>wxWindows rules</H3>
 739 <UL>
 740   <P><LI>File location and naming conventions</LI><P>
 741   <OL>
 742     <P><LI><A NAME="file_locations"></LI><B>File locations</B><P>
 743 The wxWindows files for each supported platform have their own subdirectories
 744 in "include" and "src". So, for example, there is "src/msw", "include/gtk"
 745 etc. There are also two special subdirectories called "common" and
 746 "generic". The common subdirectory contains the files which are platform
 747 independent (wxObject, wxString, ...) and the generic one the generic
 748 implementations of GUI widgets, i.e. those which use only other wxWindows
 749 classes to implement them. For the platforms where the given functionality
 750 cannot be implemented natively, the generic implementation is used and the native
 751 one is used for the others. As I feel that it becomes a bit too confusing,
 752 here is an example: wxMessageBox function is implemented natively under
 753 Windows (where it just calls MessageBox API), but there is also a generic
 754 implementation which is used under, for example, GTK. A generic class should
 755 normally have a name that distinguishes it from any platform-specific implementation.
 756 A #define will allow wxGenericMessageDialog to be wxMessageDialog on some
 757 platforms, for example.
 758
 759 <P>This scheme applies not only for the .cpp files, but also for the headers.
 760 However, as the program using wxWindows should (ideally) not use any
 761 "<TT>&#35;ifdef &lt;platform&gt;</TT>" at all, the headers are always included with
 762 "<TT>&#35;include &lt;wx/msgdlg.h&gt;</TT>" (for example). This file, in turn, includes
 763 the right header for given platform. Any new headers should conform to this
 764 setup as well to allow including <TT>&lt;wx/foo.h&gt;</TT> on any platform.<P>
 765
 766 Note that wxWindows implementation files should use quotes when including wxWindows
 767 headers, not angled brackets. Applications should use angled brackets. This
 768 ensures that the dependencies are correctly handled by the compiler.
 769
 770     <P><LI><A NAME="include_guards"></LI><B>Include guards</B><P>
 771 To minimize the compile time C++ programmers often use so called include
 772 guards: for example, in the header file foo.h you might have
 773
 774 <PRE>
 775 &#35;ifndef _FOO_H_
 776 &#35;define _FOO_H_
 777
 778 ... all header contents ...
 779
 780 &#35;endif
 781  //_FOO_H_
 782 </PRE>
 783
 784 In this way, the header will only be included once for the compilation
 785 of any .cpp (of course, it still will be included many times for the
 786 compilation of the whole project, so it has nothing to do with precompiled
 787 headers). wxWindows is no exception and also uses include guards which should use
 788 the above form, except for top-level headers which include files with identical
 789 names, in which case you should use _FOO_H_BASE_.
 790
 791     <P><LI><A NAME="pch"></LI><B>Precompiled headers</B><P>
 792 The precompiled headers greatly (we're speaking about orders of hundreds of
 793 percent here) reduce the compilation time. wxWindows uses them if the target
 794 compiler supports them (it knows about MS Visual C++, Borland C++ and g++).
 795 You should include all the headers included from <TT><wx/wx_prec.h></TT> only
 796 inside "<TT>&#35;if !USE_PRECOMP</TT>" to avoid unnecessary overhead in the case
 797 when the precompiled headers are used.<P>
 798
 799 The start of a cpp implementation file after the heading might look like this:<P>
 800
 801 <PRE>
 802 &#35;ifdef __GNUG__
 803 &#35;pragma implementation "bitmap.h"
 804 &#35;endif
 805
 806 // For compilers that support precompilation, includes "wx.h".
 807 &#35;include "wx/wxprec.h"
 808
 809 &#35;ifdef __BORLANDC__
 810 &#35;pragma hdrstop
 811 &#35;endif
 812
 813 &#35;ifndef WX_PRECOMP
 814 &#35;include &lt;stdio.h&gt;
 815 &#35;include "wx/setup.h"
 816 &#35;include "wx/list.h"
 817 &#35;include "wx/utils.h"
 818 &#35;include "wx/app.h"
 819 &#35;include "wx/palette.h"
 820 &#35;include "wx/bitmap.h"
 821 &#35;include "wx/icon.h"
 822 &#35;endif
 823
 824 &#35;include "wx/msw/private.h"
 825 &#35;include "assert.h"
 826 </PRE>
 827
 828
 829 <P>Any header file should containg the following lines:
 830 <PRE>
 831 &#35;ifdef __GNUG__
 832   &#35;pragma interface "foo.h"
 833 &#35;endif
 834 </PRE>
 835 and the corresponding .cpp file:
 836 <PRE>
 837 &#35;ifdef __GNUG__
 838   &#35;pragma  implementation "foo.h"
 839 &#35;endif
 840 </PRE> for g++ compilation.
 841   </OL>
 842
 843   <P><LI>File layout and indentation</LI><P>
 844   <OL>
 845     <P><LI><A NAME="wxwin_header"></LI><B>wxWindows standard header</B> <a href="header.txt">here</a>. The
 846 copyright holder is the original author. It is assumed the author does not assert copyright,
 847 under the terms of the wxWindows licence. This is a legal interpretation of the informal
 848 usage 'public domain' (the copyright holder does not assert the copyright).<P>
 849     <P><LI><A NAME="indentation"></LI><B>Indent your code with 4 spaces (no tabs!)</B>
 850     <P><LI><A NAME="class_decl"></LI><B>Order of parts in a class declarations</B><P>
 851   </OL>
 852
 853   <P><LI>More about naming conventions</LI><P>
 854   <OL>
 855     <P><LI><A NAME="wx_prefix"></LI><B>Use wx or WX prefix for all public symbols</B>.
 856 wx should be used for functions and classes, WX for macros.
 857     <P><LI><A NAME="wxdllexport"</LI><B>Use WXDLLEXPORT with all classes/functions in
 858                                 wxMSW/common code</B>
 859 The title says it all - every public (in the sense that it is not internal to
 860 the library) function or class should have WXDLLEXPORT macro in its
 861 declaration to allow compilation of wxWindows as shared library. For example:<P>
 862
 863 <pre>
 864 bool WXDLLEXPORT wxYield(void);
 865 class WXDLLEXPORT MyClass;  // (for forward declarations and real declarations)
 866 WXDLLEXPORT_DATA(extern wxApp*) wxTheApp;
 867 </pre>
 868
 869 The reason for the strange syntax for data is that some compilers use different
 870 keyword ordering for exporting data.
 871
 872     <P><LI><A NAME="set_get"></LI><B>Use Set/Get prefixes for accessors</B><P>
 873 There is a convention in wxWindows to prefix the accessors (i.e. any simple, in
 874 general, inline function which does nothing else except changing or returning
 875 the value of a member variable) with either <TT>Set</TT> or <TT>Get</TT>.
 876
 877     <P><LI><A NAME="constants"></LI><B>wxNAMING_CONSTANTS</B><P>
 878 The constants in wxWindows code should be defined using <TT>enum</TT> C++
 879 keyword (and not with <TT>#define</TT> or <TT>static const int</TT>). They
 880 should be declared in the global scope (and not inside class declaration) and
 881 their names should start with a <TT>wx</TT> prefix. Finally, the constants
 882 should be in all capital letters (except the first 2) to make it easier to
 883 distinguish them from the variables with underscores separating the words.
 884
 885 <P>For example, file-related constants should be declared like this:
 886 <pre>
 887 enum
 888 {
 889     wxFILEOPEN_READ,
 890     wxFILEOPEN_WRITE,
 891     wxFILEOPEN_READWRITE
 892 };
 893 </pre>
 894
 895   </OL>
 896
 897   <P><LI>Miscellaneous</LI><P>
 898   <OL>
 899     <P><LI><A NAME="forward_decl"></LI><B>Use forward declarations whenever possible</B><P>
 900 It's really a trivial piece of advice, but remember that using forward declarations
 901 instead of including the header of corresponding class is better because not
 902 only does it minimize the compile time, it also simplifies the dependencies
 903 between different source files.
 904 <P>On a related subject, in general, you should try not to include other
 905 headers from a header file.
 906
 907     <P><LI><A NAME="debug_macros"></LI><B>Use debugging macros</B><P>
 908 wxWindows provides the debugging macros <TT>wxASSERT, wxFAIL</TT> and
 909 <TT>wxCHECK_RET</TT> in <TT><wx/wx.h></TT> file. Please use them as often as
 910 you can - they will never do you any harm but can greatly simplify the bug
 911 tracking both for you and for others.
 912 <P>Also, please use <TT>wxFAIL_MSG("not implemented")</TT> instead of writing
 913 stubs for not (yet) implemented functions which silently return incorrect
 914 values - otherwise, a person using a not implemented function has no idea that
 915 it is, in fact, not implemented.
 916 <P>As all debugging macros only do something useful if the symbol
 917 <TT>__WXDEBUG__</TT> is defined, you should compile your programs in debug mode to profit
 918 from them.
 919   </OL>
 920 </UL>
 921
 922 <P>
 923
 924 <HR>
 925 Please send any comments to <A HREF=mailto:zeitlin@dptmaths.ens-cachan.fr>Vadim Zeitlin</A>.
 926
 927 </font>
 928
 929 </BODY>
 930 </HTML>