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