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