git.saurik.com Git - wxWidgets.git/blame_incremental

... / ...

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