X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/00ded554233e70a1a57c5eba385d0d9415020627..9005a56e5eedb4d032b05b5832633e700c6f0aba:/docs/html/standard.htm diff --git a/docs/html/standard.htm b/docs/html/standard.htm index 8cb5aab68b..1b8e6cf15d 100644 --- a/docs/html/standard.htm +++ b/docs/html/standard.htm @@ -24,7 +24,7 @@ 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. +for wxWindows class library.

The guide is separated into two parts: the first one addresses the general @@ -35,7 +35,7 @@ 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 +HREF="http://www.mozilla.org/hacking/portable-cpp.html" target=_top> C++ portability guide by David Williams.

@@ -55,12 +55,13 @@ C++ portability guide by David Williams.

  • General recommendations
      • +
    1. No C++ comments in C code>
    2. No global variables with constructor
    3. Turn on all warnings and eradicate them
    4. Don't rely on sizeof(int) == 2...
    5. No assignments in conditional expressions
      6. -
    6. Use #if 0 rather than comments to temporarily - disable blocks of code
      7. +
    7. Use #if 0 rather than comments to temporarily disable blocks of code
      8. +
    8. Avoid overloaded virtual functions
    9. Don't use extra semi-colons on top level

    @@ -71,15 +72,14 @@ C++ portability guide by David Williams.
  • Avoid carriage returns in cross-platform code
  • Use only lower letter filenames
  • Terminate the files with a new-line
    • +
  • Avoid globals differing by case only

  • Style choices
    1. Naming conventions: use m_ for members
      2. -
    2. Don't use void for functions without - arguments
      3. -
    3. Don't use const for non pointer/reference - arguments
      4. +
    4. Don't use void for functions without arguments
      5. +
    5. Don't use const for non pointer/reference arguments
    @@ -106,8 +106,7 @@ C++ portability guide by David Williams.
  • More about naming conventions
    1. Use wx or WX prefix for all public symbols
      2. -
    2. Use WXDLLEXPORT with all classes/functions in - wxMSW/common code
      3. +
    3. Use WXDLLEXPORT with all classes/functions in wxMSW/common code
    4. Use Set/Get prefixes for accessors
    5. wxNAMING_CONSTANTS
    @@ -363,6 +362,18 @@ which must be followed if you wish to write correct, i.e. working, progra also contains some C/C++ specific remarks in the end which are less important.
      +

    1. No C++ comments in C code>

      2. +Never use C++ comments in C code - not all C compilers/preprocessors +understand them. Although we're mainly concerned with C++ here, there are +several files in wxWindows sources tree which are compiled with C compiler. +Among them are include/wx/setup.h and include/wx/expr.h. + +Another thing related to C vs C++ preprocessor differences is that some old C +preprocessors require that all directives start in the first column (while +it's generally allowed to have any amount of whitespace before them in C++), +so you should start them in the beginning of the line in files which are +compiled with C compiler. +

    2. No global variables with constructors

      3. In C++, the constructors of global variables are called before the main() function (or WinMain() or any other program entry point) @@ -464,6 +475,70 @@ instead of The reason is simple: if there are any /* ... */ comments inside ... the second version will, of course, miserably fail. +

    3. Avoid overloaded virtual functions

      4. + +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() +

    4. Don't use extra semi-colons on top level

      5. Some compilers don't pay any attention to extra semicolons on top level, as in 

      @@ -515,6 +590,13 @@ 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.
+
+    
    5. Avoid globals differing by case only
      6. 
+The linker on VMS is case-insensitive. Therefore all external variables and
+functions which differ only in case are not recognized by the linker as
+different, so all externals should differ in more than the case only:
+i.e. GetId is the same as . 
+

    @@ -753,12 +835,6 @@ 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. -

    • Use Set/Get prefixes for accessors

    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