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