item about constants naming added
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@3743 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Vadim Zeitlin
parent
556921dc4e
commit
172d3acb55
@ -34,7 +34,7 @@ variety of platforms. The second part details the wxWindows code organization an
|
||||
its goal it to make wxWindows as uniform as possible without imposing too
|
||||
many restrictions on the programmer.
|
||||
<P>
|
||||
Acknowledgements: This guide is partly based on <A
|
||||
Acknowledgements: This guide is partly based on <A
|
||||
HREF=http://www.mozilla.org/docs/tplist/catBuild/portable-cpp.html target=_top>
|
||||
C++ portability guide</A> by David Williams.
|
||||
|
||||
@ -100,14 +100,15 @@ C++ portability guide</A> by David Williams.
|
||||
<LI><A HREF="#indentation">Indent your code with 4 spaces (no tabs!)</A></LI>
|
||||
<LI><A HREF="#class_decl">Order of parts in a class declarations</A></LI>
|
||||
</OL>
|
||||
|
||||
|
||||
<BR>
|
||||
<LI>More about naming conventions</LI>
|
||||
<OL>
|
||||
<LI><A HREF="#wx_prefix">Use wx or WX prefix for all public symbols</A></LI>
|
||||
<LI><A HREF="#wxdllexport">Use WXDLLEXPORT with all classes/functions in
|
||||
<LI><A HREF="#wxdllexport">Use WXDLLEXPORT with all classes/functions in
|
||||
wxMSW/common code</A></LI>
|
||||
<LI><A HREF="#set_get">Use Set/Get prefixes for accessors</A></LI>
|
||||
<LI><A HREF="#constants">wxNAMING_CONSTANTS</A></LI>
|
||||
</OL>
|
||||
|
||||
<BR>
|
||||
@ -123,7 +124,7 @@ C++ portability guide</A> by David Williams.
|
||||
<H3>General C++ Rules</H3>
|
||||
<UL>
|
||||
<LI>New or not widely supported C++ features</LI>
|
||||
|
||||
|
||||
<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
|
||||
supported by all compilers. Moreover, when they're supported, there are
|
||||
differences between different vendor's implementations. It's understandable that
|
||||
@ -133,7 +134,7 @@ of your favourite C++ abilities are indicated.
|
||||
<P>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,
|
||||
<I>none</I> of which supports <I>any</I> feature from the list below.
|
||||
|
||||
|
||||
<OL>
|
||||
<P><LI><A NAME="no_templates"></A><B>Don't use C++ templates</B></LI><P>
|
||||
Besides the reasons mentioned above, template usage also makes the
|
||||
@ -145,7 +146,7 @@ most commonly, polymorphic containers (in the sense that they can contain object
|
||||
any type without compromising C++ type system, i.e. using <TT>void *</TT>
|
||||
is out of question). wxWindows provides <A HREF="TODO">dynamic
|
||||
arrays and lists</A> 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
|
||||
to use them. Lack of template is not a reason to use static arrays or
|
||||
type-less (passing by <TT>void *</TT>) containers.
|
||||
|
||||
<P><LI><A NAME="no_exceptions"></A><B>Don't use C++ exceptions</B></LI><P>
|
||||
@ -180,10 +181,10 @@ might help here:<P>
|
||||
void ReadAddressBookFile(const wxString& strName)
|
||||
{
|
||||
wxFile file;
|
||||
|
||||
|
||||
if ( !file.Open(strFile) )
|
||||
return;
|
||||
|
||||
|
||||
...process it...
|
||||
}
|
||||
</PRE>
|
||||
@ -193,19 +194,19 @@ void ReadAddressBookFile(const wxString& strName)
|
||||
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'!",
|
||||
wxLogError("Can't read address book from '%s'!",
|
||||
strName.c_str());
|
||||
return false;
|
||||
}
|
||||
|
||||
|
||||
...process it...
|
||||
|
||||
|
||||
return true;
|
||||
}
|
||||
</PRE>
|
||||
@ -217,22 +218,22 @@ bool ReadAddressBookFile(const wxString& strName)
|
||||
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;
|
||||
}
|
||||
</PRE></LI>
|
||||
</UL>
|
||||
</OL>
|
||||
|
||||
|
||||
<P><LI><A NAME="no_rtti"></A><B>Don't use RTTI</B></LI><P>
|
||||
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
|
||||
@ -240,7 +241,7 @@ reason not to use it except the portability issue and the fact that it adds
|
||||
in the implementations I'm aware of).
|
||||
<P><U>Workaround</U>: 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) <TT>dynamic_cast</TT>.
|
||||
macros instead of the (horrible looking, BTW) <TT>dynamic_cast</TT>.
|
||||
|
||||
<P><LI><A NAME="no_namespaces"></A><B>Don't use namespaces</B></LI><P>
|
||||
This topic is subject to change with time, however for the moment all wxWindows
|
||||
@ -312,17 +313,17 @@ you can try the following:
|
||||
private:
|
||||
class PrivateLibClass *m_pObject;
|
||||
};
|
||||
|
||||
|
||||
// in the .cpp file
|
||||
class PrivateLibClass { ... };
|
||||
|
||||
|
||||
PublicLibClass::PublicLibClass()
|
||||
{
|
||||
m_pObject = new PrivateLibClass;
|
||||
|
||||
|
||||
...
|
||||
}
|
||||
|
||||
|
||||
PublicLibClass::~PublicLibClass()
|
||||
{
|
||||
delete m_pObject;
|
||||
@ -337,14 +338,14 @@ an example of a more general interface/implementation separation idea).
|
||||
<LI>General recommendations</B></LI><P>
|
||||
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
|
||||
C++ standard, this section contains compiler- (and language-) independent advice
|
||||
which <B>must</B> 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
|
||||
also contains some C/C++ specific remarks in the end which are less
|
||||
important.
|
||||
<OL>
|
||||
<P><LI><A NAME="no_globals"></A><B>No global variables with constructors</B></LI><P>
|
||||
In C++, the constructors of global variables are called before the
|
||||
<TT>main()</TT> function (or <TT>WinMain()</TT> or any other program entry point)
|
||||
<TT>main()</TT> function (or <TT>WinMain()</TT> or any other program entry point)
|
||||
starts executing. Thus, there is no possibility to initialize <I>anything</I>
|
||||
before the constructor call. The order of construction is largely
|
||||
implementation-defined, meaning that there is no guarantee that one global
|
||||
@ -423,7 +424,7 @@ sizes are different. A small table illustrates it quite well:
|
||||
Although close to the heart of many C programmers (I plead guilty), code like
|
||||
classical <TT>if ( (c = getchar()) != EOF )</TT> is bad because it prevents you
|
||||
from enabling "assignment in conditional expression" warning (see also
|
||||
<A HREF="#no_warnings">above</A>) warning which is helpful to detect common
|
||||
<A HREF="#no_warnings">above</A>) which is helpful to detect common
|
||||
mistypes like <TT>if ( x = 2 )</TT> instead of <TT>if ( x == 2 )</TT>.
|
||||
|
||||
<P><LI><A NAME="no_comment_code"></A><B>Use <TT>#if 0</TT> rather than comments to temporarily
|
||||
@ -495,10 +496,10 @@ 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.
|
||||
</OL>
|
||||
|
||||
|
||||
<BR>
|
||||
<LI>Style choices</B></LI><P>
|
||||
All wxWindows specific style guidelines are specified in the next
|
||||
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.
|
||||
|
||||
@ -518,9 +519,9 @@ following code fragment is:
|
||||
void Foo::Bar(int x_)
|
||||
{
|
||||
...
|
||||
|
||||
|
||||
x = x_;
|
||||
|
||||
|
||||
...
|
||||
}
|
||||
</PRE>
|
||||
@ -591,7 +592,7 @@ However, the <TT>const</TT> keyword is confusing here, adds nothing to the code
|
||||
and even cannot be removed if <TT>Foo()</TT> is virtual and overridden (because
|
||||
the names are mangled differently). So, <I>for arguments passed by value</I>
|
||||
you shouldn't use <TT>const</TT>.
|
||||
<P>Of course, it doesn't apply to functions such as
|
||||
<P>Of course, it doesn't apply to functions such as
|
||||
<TT>void PrintMessage(const char *text)</TT> where <TT>const</TT> is mandatory.
|
||||
</OL>
|
||||
</UL>
|
||||
@ -607,7 +608,7 @@ 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
|
||||
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
|
||||
@ -712,12 +713,12 @@ usage 'public domain' (the copyright holder does not assert the copyright).<P>
|
||||
<P><LI><A NAME="indentation"></LI><B>Indent your code with 4 spaces (no tabs!)</B>
|
||||
<P><LI><A NAME="class_decl"></LI><B>Order of parts in a class declarations</B><P>
|
||||
</OL>
|
||||
|
||||
|
||||
<P><LI>More about naming conventions</LI><P>
|
||||
<OL>
|
||||
<P><LI><A NAME="wx_prefix"></LI><B>Use wx or WX prefix for all public symbols</B>.
|
||||
wx should be used for functions and classes, WX for macros.
|
||||
<P><LI><A NAME="wxdllexport"</LI><B>Use WXDLLEXPORT with all classes/functions in
|
||||
<P><LI><A NAME="wxdllexport"</LI><B>Use WXDLLEXPORT with all classes/functions in
|
||||
wxMSW/common code</B>
|
||||
The title says it all - every public (in the sense that it is not internal to
|
||||
the library) function or class should have WXDLLEXPORT macro in its
|
||||
@ -734,14 +735,33 @@ keyword ordering for exporting data.
|
||||
|
||||
<P>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
|
||||
corresponding .cpp files must be taken inside
|
||||
"<TT>#if !USE_SHARED_LIBRARY</TT>" and in the <TT>#if USE_SHARED_LIBRARY</TT>
|
||||
case you should put them inside <TT>common/cmndata.cpp</TT> file.
|
||||
|
||||
<P><LI><A NAME="set_get"></LI><B>Use Set/Get prefixes for accessors</B><P>
|
||||
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
|
||||
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 <TT>Set</TT> or <TT>Get</TT>.
|
||||
|
||||
<P><LI><A NAME="constants"></LI><B>wxNAMING_CONSTANTS</B><P>
|
||||
The constants in wxWindows code should be defined using <TT>enum</TT> C++
|
||||
keyword (and not with <TT>#define</TT> or <TT>static const int</TT>). They
|
||||
should be declared in the global scope (and not inside class declaration) and
|
||||
their names should start with a <TT>wx</TT> 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.
|
||||
|
||||
<P>For example, file-related constants should be declared like this:
|
||||
<pre>
|
||||
enum
|
||||
{
|
||||
wxFILEOPEN_READ,
|
||||
wxFILEOPEN_WRITE,
|
||||
wxFILEOPEN_READWRITE
|
||||
};
|
||||
</pre>
|
||||
|
||||
</OL>
|
||||
|
||||
<P><LI>Miscellaneous</LI><P>
|
||||
@ -751,7 +771,7 @@ It's really a trivial piece of advice, but remember that using forward declarati
|
||||
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.
|
||||
<P>On a related subject, in general, you should try not to include other
|
||||
<P>On a related subject, in general, you should try not to include other
|
||||
headers from a header file.
|
||||
|
||||
<P><LI><A NAME="debug_macros"></LI><B>Use debugging macros</B><P>
|
||||
@ -764,7 +784,7 @@ 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.
|
||||
<P>As all debugging macros only do something useful if the symbol
|
||||
<TT>__DEBUG__</TT> is defined, you should compile your programs in debug mode to profit
|
||||
<TT>__WXDEBUG__</TT> is defined, you should compile your programs in debug mode to profit
|
||||
from them.
|
||||
</OL>
|
||||
</UL>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user