Amebis/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Added news and coding standards HTML files to CVS

Browse Source 
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@3224 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Julian Smart
1999-07-31 09:20:44 +00:00
parent 8bf5d46efb
commit 97979ddfbe
2 changed files with 1038 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

258
docs/html/news.htm Normal file
View File

@@ -0,0 +1,258 @@
<HTML>
<HEAD>
<TITLE>News</TITLE>
</HEAD>
<BODY BGCOLOR=#FFFFFF TEXT=#000000 LINK=#FF0000 VLINK=#000000>
<font face="Arial, Lucida Sans, Helvetica">
<table width=100% border=4 cellpadding=5 cellspacing=0>
<tr>
<td bgcolor="#660000">
<font size=+1 face="Arial, Lucida Sans, Helvetica" color="#FFFFFF">
News
</font>
</td>
</tr>
</table>
<H3>May 27th, 1999</H3><P>
<ul>
<li>Beta 1 of <a href="dl_mac2.htm">wxWindows 2 for Mac</a> has been released, thanks to Stefan Csomor's amazing efforts.
<li>Work continues on the development branch of wxWindows 2 for MSW, GTK and Motif. Vadim has been reworking the
MSW implementation to solve some internal design problems, as well as factoring out base classes to make
development easier.
<li>Work on consistent drag and drop support in GTK and MSW continues.
</ul>
<H3>March 1st, 1999</H3><P>
wxWindows 2 launch day!<P>
<ul>
<li>wxWindows 2 officially launched, after more than two years' development of
the API and ports to Windows, GTK and Motif (Mac to follow).
<a href="download.htm">Download</a> wxWindows 2.
</ul>
<H3>November 26th 1998</H3><P>
<ul>
<li><a href="ftp://www.remstar.com/pub/wxwin/1.68E">wxWindows 1.68E</a> contains minor bug fixes and now compiles with MS VC++ 6.0, and
(hopefully) BC++ 5.0, as well as Cygwin b20.
<li>The latest <a href="ftp://www.remstar.com/pub/wxwin/2.0.1">wxWindows 2.0 alpha</a> shows good progress
on the Motif port, with a tabbed MDI implementation, a nice wxToolBar class and most
major classes working. wxWindows 2.0 for Windows now works with VC++ 6.0, BC++ 5.0 and
Cygwin b20. There's a problem linking with Mingw32, I don't know why this is, perhaps
something to do with differences in the way pragmas are handled.
<li>There is also good progress with Stefan Csomor's wxMac 2.0: watch this space. A preview
is available <a href="http://www.advanced.ch/wxwin/wxmac_d1.zip">here</a>.
<li>Work is finally underway on a <a href="wxide.htm">wxWindows IDE</a>!
<li>Aleksandras Gluchovas is working on a docking window implementation and the results
are pretty impressive so far. Here's a <a href="http://www.soften.ktu.lt/~alex/fl_screenshot.gif">screenshot</a>;
source code is <a href="http://www.soften.ktu.lt/~alex/fl_src_0_1.zip">here</a> and a WIN32 executable
is <a href="http://www.soften.ktu.lt/~alex/fl_demo_exe_0_1.zip">here</a>. The source also includes
work on persistent storage classes.
</ul>
<H3>September 13th 1998</H3><P>
<ul>
<li>The main ftp site is now <a href="ftp://www.remstar.com/pub/wxwin">www.remstar.com/pub/wxwin</a>,
since the AIAI site is no longer available for uploads.
</ul>
<H3>August 23rd 1998</H3><P>
<ul>
<li>wxGTK and wxMSW 2.0 progress continues apace. The API is being unified quite successfully,
and most of the samples now compile under both ports.
<li>We are looking for <a href="sponsor.htm">sponsorship</a> of wxMotif 2.0.
</ul>
<H3>April 28th 1998</H3><P>
<ul>
<li>wxWindows 1.68C has been released. This mainly provides compatibility with Gnu-Win32 b19
and Mingw32.
<li>wxWindows 2.0 beta 9 has been released. Again, this provides Gnu-Win32 b19/Mingw32 compatibility
plus a few small bug fixes.
</ul>
<H3>March 22nd 1998</H3><P>
<ul>
<li>The mailing list addresses have changed: please see the <a href="maillist2.htm">mailing list page</a>
for details. You may need to re-subscribe if you subscribed since February 1998.
</ul>
<H3>January 5th 1998</H3><P>
<ul>
<li>Happy New Year!
<li>wxWindows 1.68B is available.
<li>wxWindows 2.0 has another port in progress - <a href="http://www.freiburg.linux.de/~wxxt" target=_top>wxGTK</a>,
by Robert Roebling (see also the information on the same page about Robert's FADE desktop
environment project).
<li>The Windows and Xt/Motif ports to 2.0 are progressing well. A large proportion of the documentation
has been done. One of the main things to resolve is how transformations (such as scaling
and translation) will be done in 2.0, but we're heading towards agreement.
<li>There is a new <a href="http://wxwin.projects.ml.org" target=_top>wxWindows Developers Site</a> in preparation, for people developing ports of
wxWindows. There are newsgroups and a wxwin-developers mailing list.
<li>40 wxWindows CD-ROMs have been sold, mostly outside the U.K.
<li>Antonia Charlotte Smart was born on November 1st 1997. Naturally, she's as cute as her parents.
</ul>
<H3>August 13th 1997</H3><P>
<ul>
<li>Added <a href="getstart.htm">Getting Started</a> page for new users.
<li>There's a good review of wxWindows by Oliver Niedung and Stefan Gunther in
<I>iX</I>, a German computer magazine.
</ul>
<H3>July 24th 1997</H3><P>
<ul>
<li>wxWindows 1.67 <a href="download.htm" target=wxmain>released</a>.
</ul>
<H3>July 22nd 1997</H3><P>
<ul>
<li>wxWindows 1.67 is nearly there...
<li>Check out <a href="apps/forty/forty.htm">Forty Thieves</a>, a great card game
by Chris Breeze of Hitachi Europe Limited.
</ul>
<H3>July 16th 1997</H3><P>
<ul>
<li>Jobst Schmalenbach has set up Australian mirrors of the wxWindows ftp and Web sites:
please see the <a href="mirrors.htm">Mirrors</a> page.
<li>Arthur Tetzlaff-Deas is starting to look afresh at a port of wxWindows 2.0 to
NeXTStep. This is more relevant now that the NeXT OS will be essential to the Apple Mac's future.
<li>The next release of wxWindows for Motif/XView/Windows should be within the next two weeks or so. I have abandoned
documentation in wxHelp form in favour of the much better quality HTML format, which I
will be including with the distribution from now on.
</ul>
<H3>July 7th 1997</H3><P>
<ul>
<li>For news on wxWindows 2.0 development, please see <a href="coming.htm">What's coming next?</a>
- developments include DLL and experimental Netscape Plugin support. The estimate for a release
date has been put back to October 1997 - to be out of the way before Smart Jr. arrives in November...
<li>Negotiations with a U.S. company about development of wxWindows into a commercial product
fell through, since it was not possible to agree about the continuation of a version
of wxWindows that maintains the free, collaborative spirit that currently exists.
</ul>
<H3>May 18th 1997</H3><P>
<ul>
<li>wxWindows 2.0 development (mostly for the Windows platform) is on track thanks to funding for wxWin-related consultancy
- thank you to those concerned! This work is still on the free version of 2.0, although an additional
commercial version may be developed sometime in the future. Markus Holzem continues to generously donate
his spare time for Motif/Xt developments, and Greg Whitehead is looking into the Mac version of 2.0.
<li>Guilhem Lavaux has contributed a first version of
<a href="ftp://www.remstar.com/pub/wxwin/contrib/wxsocket">wxSocket</a>, a set of classes for
network programming based on work by Andrew Davison. Currently this works on Motif/Xt and is coded but not yet tested
for Windows. The wxIPC classes on the UNIX side have been rewritten to take advantage of the new
classes. wxSocket is a great contribution that will be a part of wxWindows 2.0. Meanwhile, do check
it out and help Guilhem debug and develop it further.
<li>Other noteworthy contributions in recent weeks include a patch for using bitmap
<a href="ftp://www.remstar.com/pub/wxwin/contrib/unixmask">masks</a> on X for transparency
effects - another Lavaux effort! - plus <a href="ftp://www.remstar.com/pub/wxwin/contrib/wxthread">thread</a> classes
by Wolfram Gloger, updates to <a href="ftp://www.remstar.com/pub/wxwin/ports/xt">wxXt</a> by Markus Holzem,
a start at <A HREF="ftp://www.remstar.com/pub/wxwin/contrib/wxole">OLE control</a> support by Norbert Grotz,
an improved <A HREF="ftp://www.remstar.com/pub/wxwin/contrib/winstmod">Winstall</a> by Stefan Hammes,
and <A HREF="ftp://www.remstar.com/pub/wxwin/contrib/wxpref">wxPreferences</a> by Bart Jourquin
to simulate .ini files on UNIX.<P>
Check out the <A href="contrib2.htm">Contributions</a> page for more.
</ul>
<P>
<H3>May 8th 1997</H3><P>
<ul>
<li>Hitachi Europe Limited have used wxWindows both to implement and to illustrate
their WebReuser tool - a link to <a href="http://www.stablesoft.com">their pages</a> has been
added to the <a href="apps.htm">Applications</a> page.
<li>Another interesting link in the Applications page is
<a href="http://www.softwarebuero.de/wipeout-eng.html">WipeOut</a>, a C++ integrated development
environment for Linux.
<li>Fixes to make wxWindows 1.66F work with VC++ 5.0 are in the
<A href="ftp://www.remstar.com/pub/wxwin/ports/msvc50">ports/msvc50</a>
directory.
</ul>
<P>
<H3>April 20th 1997</H3><P>
<ul>
<li>wxWindows is listed in the <a href="http://SAL.KachinaTech.COM/">Scientific Applications on Linux</a> index</a>,
<a href="http://SAL.KachinaTech.COM/F/5/WXWINDOWS.html">here</a>.
<li>There is a new page for <a href="issues.htm">issues with the current release</a> which I would
encourage you to read.
<li>The wxWindows Web pages can be switched to non-frames mode, for those who find frames irritating
(and who use browsers that don't implement Back properly :-)).
<li>The <A href="contrib.htm">Contrib</a> page has some new entries.
<li>wxWindows 2.0 progress is steady.
<li><a href="mailto:grw@market.net">Greg Whitehead</a> is taking a look at what's involved for a Mac port of 2.0, possibly using MetroWerks' PowerPlant
classes to speed up development.
</ul>
<P>
<H3>March 13th 1997</H3><P>
<ul>
<li>Check out C-LAB's <a href="http://www.c-lab.de/~lipuser/lip" TARGET=_top>Lean Integration Platform</a> written in wxWindows/wxLisp: it's
a multi-platform workflow tool. Nice Web pages!
<li>I've written some <a href="prepare.htm">tips</a> to help you code for easy porting to wxWindows 2.0.
<li>wxWin 2.0 progress: I've eliminated the need for the dreaded CTL3D library for Windows 95 applications.
New MDI classes are working, plus wxStatusBar, wxScrolledWindow. Markus is starting work on the Motif
port, with wxXt 2.0 as a second priority. But <a href="sponsors.htm">financial help</a> to keep
the momentum going is needed!
</ul>
<P>
<H3>February 25th 1997</H3><P>
<ul>
<li>Yura Bidus (yari_b@automedi.com) has successfully adapted wxWindows 1.66B to compile as a DLL under
Borland C++. He will be patching 1.66F and investigating using VC++ for building the DLL.
<li>Early experiments indicate that application files using wxWindows 2.0
and GNU-WIN32 will be at least twice as fast to compile as 1.66, due to elimination of base classes
and restructuring to avoid including windows.h.
</ul>
<P>
<H3>January 29th 1997</H3><P>
<ul>
<li><a href="ftp://www.remstar.com/pub/wxwin/1.66F_internal">wxWindows 1.66F</a> has been semi-released
for people to test before the official release. It works with GNU-WIN32, and contains miscellaneous bug fixes.
<li>ITA, Inc. have sent a debugged and
enhanced <a href="ftp://www.remstar.com/pub/wxwin/ports/mac/ita">Mac port</a> (building on 1.61).
<li>Markus Holzem and Julian Smart are designing wxWindows 2.0, which should make wxWindows into a force
to be reckoned with against other free and commercial libraries. The <a href="coming.htm">What's coming next?</a>
page will shortly contain more details.
<li>The <a href="maillist.htm">mailing lists</a> are up and running again, with new subscription and discussion
list addresses.
</ul>
<P>
</font>
</BODY>
</HTML>

780
docs/html/standard.htm Normal file
View File

@@ -0,0 +1,780 @@
<HTML>
<HEAD>
<TITLE>wxWindows Programmer Style Guide</TITLE>
</HEAD>
<BODY>
<a name="top"></a>
<font face="Arial, Lucida Sans, Helvetica">
<table width=100% border=4 cellpadding=5 cellspacing=0>
<tr>
<td bgcolor="#660000">
<font size=+1 face="Arial, Lucida Sans, Helvetica" color="#FFFFFF">
wxWindows Programmer Style Guide
</font>
</td>
</tr>
</table>
<P>
by <A HREF=mailto:zeitlin@dptmaths.ens-cachan.fr>Vadim Zeitlin</A><P>
This guide is intended for people who are (or intending to start) writing code
for <A HREF="http://web.ukonline.co.uk/julian.smart/wxwin/" target=_top>wxWindows</A> class library.
<P>
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.
<P>
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.
<P>
<H3>General C++ Rules</H3>
<UL>
<LI>New or not widely supported C++ features</LI>
<OL>
<LI><A HREF="#no_templates">Don't use C++ templates</A></LI>
<LI><A HREF="#no_exceptions">Don't use C++ exceptions</A></LI>
<LI><A HREF="#no_rtti">Don't use RTTI</A></LI>
<LI><A HREF="#no_namespaces">Don't use namespaces</A></LI>
<LI><A HREF="#no_stl">Don't use STL</A></LI>
<LI><A HREF="#no_fordecl">Don't declare variables inside <TT>for()</TT></A></LI>
<LI><A HREF="#no_nestedclasses">Don't use nested classes</A></LI>
</OL>
<BR>
<LI>General recommendations</LI>
<OL>
<LI><A HREF="#no_globals">No global variables with constructor</A></LI>
<LI><A HREF="#no_warnings">Turn on all warnings and eradicate them</A></LI>
<LI><A HREF="#no_assume_sizeof">Don't rely on <TT>sizeof(int) == 2</TT>...</A></LI>
<LI><A HREF="#no_assignment_in_if">No assignments in conditional expressions</A></LI>
<LI><A HREF="#no_comment_code">Use <TT>#if 0</TT> rather than comments to temporarily
disable blocks of code</A></LI>
<LI><A HREF="#no_extra_semicolon">Don't use extra semi-colons on top level</A></LI>
</OL>
<BR>
<LI>Unix/DOS differences</LI>
<OL>
<LI><A HREF="#use_cpp_ext">Use .cpp for C++ source file extension</A></LI>
<LI><A HREF="#no_backslash">Don't use backslash ('\\') in &#35;includes</A></LI>
<LI><A HREF="#no_carriagereturn">Avoid carriage returns in cross-platform code</A></LI>
<LI><A HREF="#no_caps_in_filenames">Use only lower letter filenames</A></LI>
<LI><A HREF="#no_incomplete_files">Terminate the files with a new-line</A></LI>
</OL>
<BR>
<LI>Style choices</LI>
<OL>
<LI><A HREF="#naming_conv">Naming conventions: use <TT>m_</TT> for members</A></LI>
<LI><A HREF="#no_void_param">Don't use <TT>void</TT> for functions without
arguments</A></LI>
<LI><A HREF="#no_const_int">Don't use <TT>const</TT> for non pointer/reference
arguments</A></LI>
</OL>
</UL>
<P>
<H3>wxWindows Rules</H3>
<UL>
<LI>Files location and naming conventions</LI>
<OL>
<LI><A HREF="#file_locations">File locations</A></LI>
<LI><A HREF="#include_guards">Include guards</A></LI>
<LI><A HREF="#pch">Precompiled headers</A></LI>
</OL>
<BR>
<LI>File layout and indentation</LI>
<OL>
<LI><A HREF="#wxwin_header">wxWindows standard header</A></LI>
<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
wxMSW/common code</A></LI>
<LI><A HREF="#set_get">Use Set/Get prefixes for accessors</A></LI>
</OL>
<BR>
<LI>Miscellaneous</LI>
<OL>
<LI><A HREF="#forward_decl">Use forward declarations whenever possible</A></LI>
<LI><A HREF="#debug_macros">Use debugging macros</A></LI>
</OL>
</UL>
<HR>
<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
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.
<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
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).
<P><U>Workaround</U>: 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 <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
type-less (passing by <TT>void *</TT>) containers.
<P><LI><A NAME="no_exceptions"></A><B>Don't use C++ exceptions</B></LI><P>
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).
<P><U>Workaround</U>: 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:<P>
<OL>
<LI>Every function returns an integer (or at least boolean) error code.
<P>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 <TT>int</TT> or <TT>bool</TT> return type from the very beginning!<P>
</LI><LI>Every function you call may fail - check the return code!
<P>Never rely on the function's success, always test for a possible error.<P>
</LI><LI>Tell the user about the error, don't silently ignore them.
<P>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 <A HREF="TODO"><TT>wxLogError</TT></A> or
<A HREF="TODO"><TT>wxLogWarning</TT></A> functions. All wxWindows
functions (must) log the error messages on failure - this can be disabled
by using <A HREF="TODO">wxLogNull</A> object before calling it.
<P>Examples:<UL>
<LI><I>Wrong</I>:
<PRE>
void ReadAddressBookFile(const wxString& strName)
{
wxFile file;
if ( !file.Open(strFile) )
return;
...process it...
}
</PRE>
</LI><LI><I>Correct</I>:
<PRE>
// 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;
}
</PRE>
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 <TT>wxFile::Exists()</TT>)
we can also write:
<PRE>
// 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;
}
</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
<TT>sizeof(void *)</TT> bytes to any class having virtual functions (at least,
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>.
<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
classes/functions live in the global namespace.
<P><U>Workaround</U>: None.
<P><LI><A NAME="no_stl"></A><B>Don't use STL</B></LI><P>
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.
<P><U>Workaround</U>: 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).
<P><LI><A NAME="no_fordecl"></A><B>Don't declare variables inside <TT>for()
</TT></B></LI><P>
The scope of a variable declared inside <TT>for()</TT> statement changed several
years ago, however many compilers still will complain about second declaration
of <TT>i</TT> in the following code:
<PRE>
for ( int i = 0; i < 10; i++ ) {
...
}
...
for ( int i = 0; i < 10; i++ ) {
...
}
</PRE>
Even if it's perfectly legal now.
<P><U>Workaround</U>: write this instead:
<PRE>
int i;
for ( i = 0; i < 10; i++ ) {
...
}
...
for ( i = 0; i < 10; i++ ) {
...
}
</PRE>
<P><LI><A NAME="no_nestedclasses"></A><B>Don't use nested classes</B></LI><P>
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.
<P>Unfortunately, some compilers have trouble understanding them, so we must
sacrifice the ideals of software design to get a working program in this case.
<P><U>Workaround</U>: instead of
<PRE>
// in the header
class PublicLibClass {
...
private:
class PrivateLibClass { ... } m_object;
};
</PRE>
you can try the following:
<PRE>
// 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;
}
</PRE>
<P>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).
</OL>
<BR>
<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
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
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)
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
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 <I>any</I> variables of object (as opposed to simple:
<TT>int</TT>, ...) 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 <TT>new</TT>
and <TT>delete</TT> operators (overloaded in wxWindows), especially because the first <TT>new</TT> called
is the standard one (before wxWindows overloads them) and <TT>delete</TT> will
be the overloaded operator.
<P><LI><A NAME="no_warnings"></A><B>Turn on all warnings and eradicate them</B></LI><P>
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.
<P><LI><A NAME="no_assume_sizeof"></A><B>Don't rely on <TT>sizeof(int) == 2</TT>...</B></LI><P>
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:
<TABLE BORDER COLS=5 WIDTH="100%" NOSAVE >
<TR>
<TD>Architecture/OS</TD>
<TD>sizeof(short)</TD>
<TD>sizeof(int)</TD>
<TD>sizeof(long)</TD>
<TD>sizeof(void *)</TD>
</TR>
<TR>
<TD>i386/Windows 3.1</TD>
<TD>2</TD>
<TD>2</TD>
<TD>4</TD>
<TD>2 or 4</TD>
</TR>
<TR>
<TD>i386/Windows 95</TD>
<TD>2</TD>
<TD>4</TD>
<TD>4</TD>
<TD>4</TD>
</TR>
<TR>
<TD>Merced/Win64</TD>
<TD>2</TD>
<TD>4</TD>
<TD>4</TD>
<TD>8</TD>
</TR>
<TR>
<TD>Alpha/Linux</TD>
<TD>???</TD>
<TD>???</TD>
<TD>???</TD>
<TD>???</TD>
</TR>
</TABLE>
<P><LI><A NAME="no_assignment_in_if"></A><B>No assignments in conditional expressions</B></LI><P>
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
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
disable blocks of code</B></LI><P>
If you have to temporarily disable some code, use
<PRE>
#if 0 // VZ: I think this code is unneeded, it probably must be removed
...
#endif // 0
</PRE>
instead of
<PRE>
/*
...
*/
</PRE>
The reason is simple: if there are any <TT>/* ... */</TT> comments inside
<TT>...</TT> the second version will, of course, miserably fail.
<P><LI><A NAME="no_extra_semicolon"></A><B>Don't use extra semi-colons on top level</B></LI><P>
Some compilers don't pay any attention to extra semicolons on top level, as in
<PRE>
class Foo { };;
</PRE>
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
(<TT>IMPLEMENT_something</TT>, for example) which already has a ';' inside and
put another one after it.
</OL>
<BR>
<LI>Unix/DOS differences</B></LI><P>
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.
<OL>
<P><LI><A NAME="use_cpp_ext"></A><B>Use .cpp for C++ source file extension</B></LI><P>
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.
<P><LI><A NAME="no_backslash"></A><B>Don't use backslash ('\\') in &#35;includes</B></LI><P>
Although it's too silly to mention, please don't use backslashes in
<TT>&#35;include</TT> preprocessor statement. Even not all Windows compilers accept
it, without speaking about all other ones.
<P><LI><A NAME="no_carriagereturn"></A><B>Avoid carriage returns in cross-platform code</B></LI><P>
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
(= <Ctrl-M> = '\r') in C/C++ code.
<P><LI><A NAME="no_caps_in_filenames"></A><B>Use only lower case filenames</B></LI><P>
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.
<P><LI><A NAME="no_incomplete_files"></A><B>Terminate the files with a new-line</B></LI><P>
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.
</OL>
<BR>
<LI>Style choices</B></LI><P>
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.
<OL>
<P><LI><A NAME="naming_conv"></A><B>Naming conventions: use <TT>m_</TT> for members</B></LI><P>
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.
<P>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 <I>cannot</I> say what <TT>x</TT> in the
following code fragment is:
<PRE>
void Foo::Bar(int x_)
{
...
x = x_;
...
}
</PRE>
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 <TT>x = x_</TT> line), a
member variable or a global variable - you have no way of knowing.
<P>The wxWindows naming convention gives you, the reader of the code, much more
information about <TT>x</TT>. In the code above you know that it's a local
variable because:<P>
<OL>
<LI>global variables are always prefixed with <TT>g_</TT></LI>
<LI>member variables are always prefixed with <TT>m_</TT></LI>
<LI>static variables are always prefixed with <TT>s_</TT></LI>
</OL>
<P>Examples:
<PRE>
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;
};
</PRE>
As you see, it also solves once and for all the old C++ programmer's question:
how to call <TT>SetX()</TT> parameter? The answer is simple: just call it
<TT>x</TT> because there is no ambiguity with <TT>Foo::m_x</TT>.
<P>The prefixes can be combined to give <TT>ms_</TT> and <TT>gs_</TT> for static
member (a.k.a. class) variables and static global variables.
<P>The convention is, of course, completely worthless if it is not followed:
nothing like being sure that <TT>x</TT> is a local variable in the code fragment
above and discovering later the following lines in the header:
<PRE>
class Foo {
...
int x; // I don't like wxWindows naming convention
};
</PRE>
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 <I>Hungarian notation</I>
which is used in wxMSW part of wxWindows code and which encodes the <I>type</I>
of the variable in its name - it is actually quite useful in C, but has little
or no sense in C++.
<P><LI><A NAME="no_void_param"></A><B>Don't use <TT>void</TT> for functions without
arguments</B></LI><P>
In ANSI C, <TT>void Foo()</TT> takes an arbitrary number of arbitrarily typed
arguments (although the form <TT>void Foo(...)</TT> is preferred) and <TT>void
Foo(void)</TT> 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 <TT>void</TT> 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.
<P><LI><A NAME="no_const_int"></A><B>Don't use <TT>const</TT> for non pointer/reference
arguments</B></LI><P>
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 <TT>void Foo(int)</TT> and <TT>void Foo(const int)</TT>.
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
<TT>void PrintMessage(const char *text)</TT> where <TT>const</TT> is mandatory.
</OL>
</UL>
<P>
<H3>wxWindows rules</H3>
<UL>
<P><LI>File location and naming conventions</LI><P>
<OL>
<P><LI><A NAME="file_locations"></LI><B>File locations</B><P>
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.
<P>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
"<TT>&#35;ifdef &lt;platform&gt;</TT>" at all, the headers are always included with
"<TT>&#35;include &lt;wx/msgdlg.h&gt;</TT>" (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 <TT>&lt;wx/foo.h&gt;</TT> on any platform.<P>
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?).
<P><LI><A NAME="include_guards"></LI><B>Include guards</B><P>
To minimize the compile time C++ programmers often use so called include
guards: for example, in the header file foo.h you might have
<PRE>
&#35;ifndef _FOO_H_
&#35;define _FOO_H_
... all header contents ...
&#35;endif
//_FOO_H_
</PRE>
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_.
<P><LI><A NAME="pch"></LI><B>Precompiled headers</B><P>
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 <TT><wx/wx_prec.h></TT> only
inside "<TT>&#35;if !USE_PRECOMP</TT>" to avoid unnecessary overhead in the case
when the precompiled headers are used.<P>
The start of a cpp implementation file after the heading might look like this:<P>
<PRE>
&#35;ifdef __GNUG__
&#35;pragma implementation "bitmap.h"
&#35;endif
// For compilers that support precompilation, includes "wx.h".
&#35;include "wx/wxprec.h"
&#35;ifdef __BORLANDC__
&#35;pragma hdrstop
&#35;endif
&#35;ifndef WX_PRECOMP
&#35;include &lt;stdio.h&gt;
&#35;include "wx/setup.h"
&#35;include "wx/list.h"
&#35;include "wx/utils.h"
&#35;include "wx/app.h"
&#35;include "wx/palette.h"
&#35;include "wx/bitmap.h"
&#35;include "wx/icon.h"
&#35;endif
&#35;include "wx/msw/private.h"
&#35;include "assert.h"
</PRE>
<P>Any header file should containg the following lines:
<PRE>
&#35;ifdef __GNUG__
&#35;pragma interface "foo.h"
&#35;endif
</PRE>
and the corresponding .cpp file:
<PRE>
&#35;ifdef __GNUG__
&#35;pragma implementation "foo.h"
&#35;endif
</PRE> for g++ compilation.
</OL>
<P><LI>File layout and indentation</LI><P>
<OL>
<P><LI><A NAME="wxwin_header"></LI><B>wxWindows standard header</B> <a href="header.txt">here</a>. The
copyright holder is the original author. It is assumed the author does not assert copyright,
under the terms of the wxWindows licence. This is a legal interpretation of the informal
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
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
declaration to allow compilation of wxWindows as shared library. For example:<P>
<pre>
bool WXDLLEXPORT wxYield(void);
class WXDLLEXPORT MyClass; // (for forward declarations and real declarations)
WXDLLEXPORT_DATA(extern wxApp*) wxTheApp;
</pre>
The reason for the strange syntax for data is that some compilers use different
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
"<TT>&#35;if !USE_SHARED_LIBRARY</TT>" and in the <TT>&#35;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
the value of a member variable) with either <TT>Set</TT> or <TT>Get</TT>.
</OL>
<P><LI>Miscellaneous</LI><P>
<OL>
<P><LI><A NAME="forward_decl"></LI><B>Use forward declarations whenever possible</B><P>
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.
<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>
wxWindows provides the debugging macros <TT>wxASSERT, wxFAIL</TT> and
<TT>wxCHECK_RET</TT> in <TT><wx/wx.h></TT> file. Please use them as often as
you can - they will never do you any harm but can greatly simplify the bug
tracking both for you and for others.
<P>Also, please use <TT>wxFAIL_MSG("not implemented")</TT> 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.
<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
from them.
</OL>
</UL>
<P>
<HR>
Please send any comments to <A HREF=mailto:zeitlin@dptmaths.ens-cachan.fr>Vadim Zeitlin</A>.
</font>
</BODY>
</HTML>