| - -wxWindows Programmer Style Guide - - | -
- -by Vadim Zeitlin
- -This guide is intended for people who are (or intending to start) writing code -for wxWindows class library. - -
-The guide is separated into two parts: the first one addresses the general -compatibility issues and is not wxWindows-specific. The advises in this part -will hopefully help you to write programs which compile and run on greater -variety of platforms. The second part details the wxWindows code organization and -its goal it to make wxWindows as uniform as possible without imposing too -many restrictions on the programmer. -
-Acknowledgements: This guide is partly based on -C++ portability guide by David Williams. - -
-
- -
The usage of all features in this section is not recommended for one reason: they appeared in C++ relatively recently and are not yet -supported by all compilers. Moreover, when they're supported, there are -differences between different vendor's implementations. It's understandable that -you might love one (or all) of these features, but you surely can write C++ -programs without them. Where possible, workarounds to compensate for absence -of your favourite C++ abilities are indicated. -
Just to suppress any doubts that there are compilers which don't support -these new features, you can think about Win16 (a.k.a. Win 3.1) compilers, -none of which supports any feature from the list below. - -
-Besides the reasons mentioned above, template usage also makes the -program compile much slower (200%-300% is not uncommon) and their support -even in the compilers which have had it for a long time is far from perfect -(the best example is probably gcc). -
Workaround: The things you would like to use templates for are, -most commonly, polymorphic containers (in the sense that they can contain objects of -any type without compromising C++ type system, i.e. using void * -is out of question). wxWindows provides dynamic -arrays and lists which are sufficient in 99% of cases - please don't hesitate -to use them. Lack of template is not a reason to use static arrays or -type-less (passing by void *) containers. - -
-The C++ exception system is an error-reporting mechanism. Another reasons not to use it, -besides portability, are the performance penalty it imposes (small, but, at least for -current compilers, non-zero), and subtle problems with -memory/resource deallocation it may create (the place where you'd like to use -C++ exceptions most of all are the constructors, but you need to be very -careful in order to be able to do it). -
Workaround: there is no real workaround, of course, or the exceptions -wouldn't have been added to the language. However, there are several rules which -might help here:
- -
There is no such thing as a function that never fails - even if it can't - fail now, it might do it later, when modified to be more powerful/general. - Put the int or bool return type from the very beginning!
-
Never rely on the function's success, always test for a possible error.
-
Exceptions are always caught and, normally, processed when they're - caught. In the same manner, the error return code must always be processed - somehow. You may choose to ignore it, but at least tell the user that - something wrong happened using wxLogError or - wxLogWarning functions. All wxWindows - functions (must) log the error messages on failure - this can be disabled - by using wxLogNull object before calling it. -
Examples:
-void ReadAddressBookFile(const wxString& strName)
-{
- wxFile file;
-
- if ( !file.Open(strFile) )
- return;
-
- ...process it...
-}
-
-
-// returns false if the address book couldn't be read
-bool ReadAddressBookFile(const wxString& strName)
-{
- wxFile file;
-
- if ( !file.Open(strFile) ) {
- // wxFile logged an error because file couldn't be opened which
- // contains the system error code, however it doesn't know what
- // this file is for and an error message "can't open $GLCW.ADB"
- // can be quite confusing for the user. Here we say what we mean.
- wxLogError("Can't read address book from '%s'!",
- strName.c_str());
- return false;
- }
-
- ...process it...
-
- return true;
-}
-
- or, if it's not an error if file doesn't exist (here we could just check
- its existence, but let's suppose that there is no wxFile::Exists())
- we can also write:
-
-// returns false if address book file doesn't exist
-bool ReadAddressBookFile(const wxString& strName)
-{
- wxFile file;
-
- // start a block inside which all log messages are suppressed
- {
- wxLogNull noLog;
- if ( !file.Open(strFile) )
- return false;
- }
-
- ...process it...
-
- return true;
-}
- -RTTI stands for Run-Time Type Information and there is probably no other -reason not to use it except the portability issue and the fact that it adds -sizeof(void *) bytes to any class having virtual functions (at least, -in the implementations I'm aware of). -
Workaround: use wxWindows RTTI system which allows you to do almost -everything which the new C++ RTTI, except that, of course, you have to use -macros instead of the (horrible looking, BTW) dynamic_cast. - -
-This topic is subject to change with time, however for the moment all wxWindows -classes/functions live in the global namespace. -
Workaround: None. - -
-STL is the new C++ standard library, proposing all kinds of template containers -and generic algorithm implementations. Templates are the heart (and almost -everything else) of the library, so its usage is out of question. Besides, even -with the compilers which do support templates, STL has many of its own problems, -there are many "not 100% standard compatible" vendor implementations, none of existing debuggers understands its -complicated data structures, ... the list can go on (almost) forever. -
Workaround: Use wxString, dynamic arrays and lists and other wxWindows -classes. wxString has many of the most often used functions of std::string STL -class (typedef to be precise). -
-The scope of a variable declared inside for() statement changed several -years ago, however many compilers still will complain about second declaration -of i in the following code: -
- for ( int i = 0; i < 10; i++ ) {
- ...
- }
-
- ...
-
- for ( int i = 0; i < 10; i++ ) {
- ...
- }
-
-Even if it's perfectly legal now.
-Workaround: write this instead: -
- int i;
- for ( i = 0; i < 10; i++ ) {
- ...
- }
-
- ...
-
- for ( i = 0; i < 10; i++ ) {
- ...
- }
-
-
- -Nested classes are, without doubt, a very good thing because they allow to hide -"private" (in the sense that they're used only inside the library) classes and, -generally, put the related things together. -
Unfortunately, some compilers have trouble understanding them, so we must -sacrifice the ideals of software design to get a working program in this case. -
Workaround: instead of -
- // in the header
- class PublicLibClass {
- ...
- private:
- class PrivateLibClass { ... } m_object;
- };
-
-you can try the following:
-
- // in the header
- class PrivateLibClass; // fwd decl
- class PublicLibClass {
- ...
- private:
- class PrivateLibClass *m_pObject;
- };
-
- // in the .cpp file
- class PrivateLibClass { ... };
-
- PublicLibClass::PublicLibClass()
- {
- m_pObject = new PrivateLibClass;
-
- ...
- }
-
- PublicLibClass::~PublicLibClass()
- {
- delete m_pObject;
- }
-
-A nice side effect is that you don't need to recompile all the files -including the header if you change the PrivateLibClass declaration (it's -an example of a more general interface/implementation separation idea). - -
- The ternary operator ?: shouldn't be used with objects (i.e. if any -of its operands are objects) because some compilers (notable Borland C++) fail -to compile such code. -
Workaround: use if/else instead. -
- wxString s1, s2; - - // Borland C++ won't compile the line below - wxString s = s1.Len() < s2.Len() ? s1 : s2; - - // but any C++ compiler will compile this - wxString s; - if ( s1.Len() < s2.Len() ) - s = s1; - else - s = s2; --
-While the recommendations in the previous section may not apply to you if you're -only working with perfect compilers which implement the very newest directives of -C++ standard, this section contains compiler- (and language-) independent advice -which must be followed if you wish to write correct, i.e. working, programs. It -also contains some C/C++ specific remarks in the end which are less -important. -
-In C++, the constructors of global variables are called before the -main() function (or WinMain() or any other program entry point) -starts executing. Thus, there is no possibility to initialize anything -before the constructor call. The order of construction is largely -implementation-defined, meaning that there is no guarantee that one global -object will be initialized before another one (except if they are both defined -in the same translation unit, i.e. .cpp file). Most importantly, no custom -memory allocation operators are installed at the moment of execution of global -variables constructors, so a (less restrictive) rule is that you should have -no global variables which allocate memory (or do anything else non-trivial) in -the constructor. Of course, if an object doesn't allocate memory in its constructor -right now, it may start making it later, so you can only be sure about this if -you don't use any variables of object (as opposed to simple: -int, ...) types. Example: currently, wxString doesn't allocate memory -in its default constructor, so you might think that having a global (initially) -empty wxString is safe. However, if wxString starts allocating some minimal -amount of memory in its default constructor (which doesn't look unreasonable), -you would have all kinds of problems with new -and delete operators (overloaded in wxWindows), especially because the first new called -is the standard one (before wxWindows overloads them) and delete will -be the overloaded operator. - -
-Give the compiler a chance to help you - turn on all warnings! You should always -use the maximum available warning level of your compiler and understand and -correct each of them. If, for whatever reasons, a compiler gives a warning on -some perfectly legal line of code and you can't change it, please insert a -comment indicating it in the code. Most oftenly, however, all compiler warnings -may be avoided (not suppressed!) with minimal changes to your code. - -
-You should never assume any absolute constraints on data type sizes. Currently, -we have 16-bit, 32-bit and 64-bit machines and even inside each class data type -sizes are different. A small table illustrates it quite well: -
| Architecture/OS | -sizeof(short) | -sizeof(int) | -sizeof(long) | -sizeof(void *) | -
| i386/Windows 3.1 | -2 | -2 | -4 | -2 or 4 | -
| i386/Windows 95 | -2 | -4 | -4 | -4 | -
| Merced/Win64 | -2 | -4 | -4 | -8 | -
| Alpha/Linux | -??? | -??? | -??? | -??? | -
-Although close to the heart of many C programmers (I plead guilty), code like -classical if ( (c = getchar()) != EOF ) is bad because it prevents you -from enabling "assignment in conditional expression" warning (see also -above) which is helpful to detect common -mistypes like if ( x = 2 ) instead of if ( x == 2 ). - -
-If you have to temporarily disable some code, use -
- #if 0 // VZ: I think this code is unneeded, it probably must be removed - ... - #endif // 0 --instead of -
- /* - ... - */ --The reason is simple: if there are any /* ... */ comments inside -... the second version will, of course, miserably fail. - -
- -You should avoid having overloaded virtual methods in a base class because if -any of them is overriden in a derived class, then all others must be overriden -as well or it would be impossible to call them on an object of derived class. - -For example, the following code: - -
- class Base
- {
- public:
- virtual void Read(wxFile& file);
- virtual void Read(const wxString& filename);
- };
-
- class Derived : public Base
- {
- public:
- virtual void Read(wxFile& file) { ... }
- };
-
- ...
-
- Derived d;
- d.Read("some_filename"); // compile error here!
-
-
-will fail to compile because the base class function taking filename
-is hidden by the virtual function overriden in the derived class (this is
-known as [virtual] function name hiding problem in C++).
-
--The standard solution to this problem in wxWindows (where we have such -situations quite often) is to make both Read() functions not virtual -and introduce a single virtual function DoRead(). Usually, it makes -sense because the function taking a filename is (again, usually) implemented -in terms of the function reading from a file anyhow (but making only this -functions not virtual won't solve the above problem!). -
-So, the above declarations should be written as: -
- class Base
- {
- public:
- void Read(wxFile& file);
- void Read(const wxString& filename);
-
- protected:
- virtual void DoRead(wxFile& file);
- };
-
- class Derived : public Base
- {
- protected:
- virtual void DoRead(wxFile& file) { ... }
- };
-
-
-This technique is widely used in many of wxWindows classes - for example,
-wxWindow has more than a dozen of DoXXX() functions which
-allows to have many overloaded versions of commonly used methods such as
-SetSize()
-
- -Some compilers don't pay any attention to extra semicolons on top level, as in -
- class Foo { };;
-
-while others complain loudly about it. Of course, you would rarely put 2
-semicolons yourself, but it may happen if you're using a macro
-(IMPLEMENT_something, for example) which already has a ';' inside and
-put another one after it.
- - Two operating systems supported by wxWindows right now are (different flavours -of) Unix and Windows 3.1/95/NT (although Mac, OS/2 and other ports exist/are -being developed as well). The main differences between them are summarized -here. - -
-There is, unfortunately, no standard exceptions for C++ source files. Different -people use .C, .cc, .cpp, .cxx, .c++ and probably several others I forgot. Some -compilers don't care about extension, but there are also other ones which can't -be made to compile any file with "wrong" extension. Such compilers are very -common in DOS/Windows land, that's why the .cpp extension is the least likely to -cause any problems - it's the standard one under DOS and will probably be -accepted by any Unix compiler as well (any counter examples?). The extension -for the header files is .h. - -
-Although it's too silly to mention, please don't use backslashes in -#include preprocessor statement. Even not all Windows compilers accept -it, without speaking about all other ones. - -
-This problem will hopefully not arise at all, with CVS taking care of this
-stuff, however it's perhaps not useless to remember that many Unix compilers
-(including, but not limited to, gcc) don't accept carriage returns
-(=
-DOS/Windows 3.1 isn't case sensitive, Windows 95/NT are case preserving, but not
-case sensitive. To avoid all kinds of problems with compiling under Unix (or
-any other fully case-sensitive OS), please use only lower case letters in the
-filenames.
-
-
-While DOS/Windows compilers don't seem to mind, their Unix counterparts don't
-like files without terminating new-line. Such files also give a warning message
-when loaded to vim (the Unix programmer's editor of choice :-)), so please think
-about terminating the last line.
-
- All wxWindows specific style guidelines are specified in the next -section, here are the choices which are not completely arbitrary, -but have some deeper and not wxWindows-specific meaning. - -
-It's extremely important to write readable code. One of the first steps in this -direction is the choice of naming convention. It may be quite vague or strictly -define the names of all the variables and function in the program, however it -surely must somehow allow the reader to distinguish between variable and -functions and local variables and member variables from the first glance. -
The first requirement is commonly respected, but for some strange reasons, the -second isn't, even if it's much more important because, after all, the immediate -context usually allows you to distinguish a variable from a function in -C/C++ code. On the other hand, you cannot say what x in the -following code fragment is: -
- void Foo::Bar(int x_)
- {
- ...
-
- x = x_;
-
- ...
- }
-
-It might be either a local variable (unluckily the function is too long so you
-don't see the variable declarations when you look at x = x_ line), a
-member variable or a global variable - you have no way of knowing.
-The wxWindows naming convention gives you, the reader of the code, much more -information about x. In the code above you know that it's a local -variable because:
-
Examples: -
- extern int g_x; // of course, 'x' is not the best name for a global...
-
- void Bar()
- {
- int x;
- }
-
- class Foo {
- public:
- void SetX(int x) { m_x = x; }
- private:
- int m_x;
- };
-
-As you see, it also solves once and for all the old C++ programmer's question:
-how to call SetX() parameter? The answer is simple: just call it
-x because there is no ambiguity with Foo::m_x.
-The prefixes can be combined to give ms_ and gs_ for static -member (a.k.a. class) variables and static global variables. -
The convention is, of course, completely worthless if it is not followed: -nothing like being sure that x is a local variable in the code fragment -above and discovering later the following lines in the header: -
- class Foo {
- ...
- int x; // I don't like wxWindows naming convention
- };
-
-Please do use these prefixes, they make your code much easier to read. Also
-please notice that it has nothing to do with the so-called Hungarian notation
-which is used in wxMSW part of wxWindows code and which encodes the type
-of the variable in its name - it is actually quite useful in C, but has little
-or no sense in C++.
-
- -In ANSI C, void Foo() takes an arbitrary number of arbitrarily typed -arguments (although the form void Foo(...) is preferred) and void -Foo(void) doesn't take any arguments. In C++, however, the situation is -different and both declarations are completely equivalent. As there is no need -to write void in this situation, let's not write it - it can only be -confusing and create an impression that it really means something when it's not -at all the case. - -
-In both C and C++ an argument passed by value cannot be modified - or, more -precisely, if it is modified in the called function, only the local copy is -really changed, not the caller's variable. So, semantically speaking, there is -no difference between void Foo(int) and void Foo(const int). -However, the const keyword is confusing here, adds nothing to the code -and even cannot be removed if Foo() is virtual and overridden (because -the names are mangled differently). So, for arguments passed by value -you shouldn't use const. -
Of course, it doesn't apply to functions such as -void PrintMessage(const char *text) where const is mandatory. -
- -
-
-The wxWindows files for each supported platform have their own subdirectories -in "include" and "src". So, for example, there is "src/msw", "include/gtk" -etc. There are also two special subdirectories called "common" and -"generic". The common subdirectory contains the files which are platform -independent (wxObject, wxString, ...) and the generic one the generic -implementations of GUI widgets, i.e. those which use only other wxWindows -classes to implement them. For the platforms where the given functionality -cannot be implemented natively, the generic implementation is used and the native -one is used for the others. As I feel that it becomes a bit too confusing, -here is an example: wxMessageBox function is implemented natively under -Windows (where it just calls MessageBox API), but there is also a generic -implementation which is used under, for example, GTK. A generic class should -normally have a name that distinguishes it from any platform-specific implementation. -A #define will allow wxGenericMessageDialog to be wxMessageDialog on some -platforms, for example. - -
This scheme applies not only for the .cpp files, but also for the headers. -However, as the program using wxWindows should (ideally) not use any -"#ifdef <platform>" at all, the headers are always included with -"#include <wx/msgdlg.h>" (for example). This file, in turn, includes -the right header for given platform. Any new headers should conform to this -setup as well to allow including <wx/foo.h> on any platform.
- -Note that wxWindows implementation files should use quotes when including wxWindows -headers, not angled brackets. Applications should use angled brackets. There -is a reason for it (can anyone remember what this is?). - -
-To minimize the compile time C++ programmers often use so called include -guards: for example, in the header file foo.h you might have - -
-#ifndef _FOO_H_ -#define _FOO_H_ - -... all header contents ... - -#endif - //_FOO_H_ -- -In this way, the header will only be included once for the compilation -of any .cpp (of course, it still will be included many times for the -compilation of the whole project, so it has nothing to do with precompiled -headers). wxWindows is no exception and also uses include guards which should use -the above form, except for top-level headers which include files with identical -names, in which case you should use _FOO_H_BASE_. - -
-The precompiled headers greatly (we're speaking about orders of hundreds of
-percent here) reduce the compilation time. wxWindows uses them if the target
-compiler supports them (it knows about MS Visual C++, Borland C++ and g++).
-You should include all the headers included from
- -The start of a cpp implementation file after the heading might look like this:
- -
-#ifdef __GNUG__ -#pragma implementation "bitmap.h" -#endif - -// For compilers that support precompilation, includes "wx.h". -#include "wx/wxprec.h" - -#ifdef __BORLANDC__ -#pragma hdrstop -#endif - -#ifndef WX_PRECOMP -#include <stdio.h> -#include "wx/setup.h" -#include "wx/list.h" -#include "wx/utils.h" -#include "wx/app.h" -#include "wx/palette.h" -#include "wx/bitmap.h" -#include "wx/icon.h" -#endif - -#include "wx/msw/private.h" -#include "assert.h" -- - -
Any header file should containg the following lines: -
-#ifdef __GNUG__ - #pragma interface "foo.h" -#endif --and the corresponding .cpp file: -
-#ifdef __GNUG__ - #pragma implementation "foo.h" -#endif -for g++ compilation. -
-
-
-
-
- -
-bool WXDLLEXPORT wxYield(void); -class WXDLLEXPORT MyClass; // (for forward declarations and real declarations) -WXDLLEXPORT_DATA(extern wxApp*) wxTheApp; -- -The reason for the strange syntax for data is that some compilers use different -keyword ordering for exporting data. - -
There also several other places where you should take care of shared -library case: all IMPLEMENT_xxx macros which are usually used in the -corresponding .cpp files must be taken inside -"#if !USE_SHARED_LIBRARY" and in the #if USE_SHARED_LIBRARY -case you should put them inside common/cmndata.cpp file. - -
-There is a convention in wxWindows to prefix the accessors (i.e. any simple, in -general, inline function which does nothing else except changing or returning -the value of a member variable) with either Set or Get. - -
-The constants in wxWindows code should be defined using enum C++ -keyword (and not with #define or static const int). They -should be declared in the global scope (and not inside class declaration) and -their names should start with a wx prefix. Finally, the constants -should be in all capital letters (except the first 2) to make it easier to -distinguish them from the variables with underscores separating the words. - -
For example, file-related constants should be declared like this: -
-enum
-{
- wxFILEOPEN_READ,
- wxFILEOPEN_WRITE,
- wxFILEOPEN_READWRITE
-};
-
-
- -
-It's really a trivial piece of advice, but remember that using forward declarations -instead of including the header of corresponding class is better because not -only does it minimize the compile time, it also simplifies the dependencies -between different source files. -
On a related subject, in general, you should try not to include other -headers from a header file. - -
-wxWindows provides the debugging macros wxASSERT, wxFAIL and
-wxCHECK_RET in
Also, please use wxFAIL_MSG("not implemented") instead of writing -stubs for not (yet) implemented functions which silently return incorrect -values - otherwise, a person using a not implemented function has no idea that -it is, in fact, not implemented. -
As all debugging macros only do something useful if the symbol -__WXDEBUG__ is defined, you should compile your programs in debug mode to profit -from them. -
- -