Coding Guidelines Proposals

84 views
Skip to first unread message

Alexandru Pana

unread,
Mar 16, 2014, 5:53:42 AM3/16/14
to wx-...@googlegroups.com
It seems the coding guidelines have been getting a lot of attention
lately, especially from the GSoC attendees such as myself.

It would probabily be a good ideea to update them, and I think people
should have a say in what the final version looks like. I believe this
thread could be used to make proposals and I will start with my own:

1. Clearly state what C++ standard is supported. Taking decisions based
on out-of-date compilers shouldn't be acceptable. We live in a world
where C++11 is gaining wide adoption and rules that forbid the use of
basic features (e.g. ternary operator or automatic arrays 
initializers) should no longer be accepted. If a certain compiler fails
to correctly implement the C++ standard, it is the compiler's fault.
C++ code should be written with regards to the standard and its
implementation in the few major compilers that are used today.

2. Discourage the use of the preprocessor. Currently, the preprocessor
is used for everything from defining platform-dependent values to
accessing data members, implementing functions and defining constants.
As anyone familiar with the C++ literature would know the preprocessor
is highly discouraged. (e.g. Effective C++ Item 2).

3. Templates should continue to be disallowed. They are the least
understood part of the C++ language by developers and wxWidgets already
has features to compensate for them.

4. Encourage the use of small functions. Functions are not only usefull
for preventing repetition, they are also usefull for giving a name to a
block of code. Functions that are implemented in terms of other functions
are much easier to read because they are self documented.

5. Discourage the abuse of comments. Good code is self documented.
Comments are thus required only when the implementation is too ugly to
be understood. We should strive to avoid such implementations. Also
separators such as:
// -------------------------------------------------------------------
// event types and macros
// -------------------------------------------------------------------
only add clutter and distract the reader from the actual code.

6. Consider adopting a standard way of documenting public interfaces.

Being mentioned in Bjarne Stroustrup's new book is surely a worthy
achievement, but I believe it's crucial to also keep up with the new C++
language also mentioned in his book.

Please take the time to comment and contribute to these proposals.

Vadim Zeitlin

unread,
Mar 16, 2014, 8:56:21 AM3/16/14
to wx-...@googlegroups.com
On Sun, 16 Mar 2014 02:53:42 -0700 (PDT) Alexandru Pana wrote:

AP> It seems the coding guidelines have been getting a lot of attention
AP> lately, especially from the GSoC attendees such as myself.

Yes, I've started updating it yesterday. I'll try to finish it during the
next week.

AP> 1. Clearly state what C++ standard is supported.

There won't be any revolution here. I do use, with a lot of pleasure,
C++11 in my own projects but we still need to support much older compilers.
We did finally drop support VC6 in 3.1 but all this means is that we can
now use (most of) C++98.

AP> 2. Discourage the use of the preprocessor.

This is not directly related to wxWidgets coding standards. This document
doesn't intend to be a general purpose C++ programming style. Obviously,
macros shouldn't be used unnecessarily. Equally obviously, conditional
compilation (which is also "preprocessor") is unavoidable in wxWidgets code
base.

AP> 3. Templates should continue to be disallowed.

This completely flies in the face of (2). And I generally just have no
idea where does this one come from. We do allow use of templates in our
code and notably strongly encourage the use of wxVector<> instead of the
old macro-based container classes. The only limitation on the use of
templates was the extremely poor support for them in VC6 but this is
(finally!) no longer a concern in 3.1. And any code should be clear and
readable, whether it uses templates or not, so while the code using
template metaprogramming can be confusing, it's an argument against writing
confusing code, not against using templates.

AP> 4. Encourage the use of small functions.

See (2).

AP> 5. Discourage the abuse of comments.

Sorry, this is nonsense. Some comments are superfluous, but I've never
seen the worst kind of offenders, such as the notorious

i++; // This increments i.

in wxWidgets code base. The organizational "comments" (e.g. the standard
header comments, delimiters between different parts of files and so on) are
mostly a question of style and with all the other matters of style we are
going to continue using them just to keep the code internally consistent.
And other than that there is absolutely no abuse of comments in wxWidgets.
As always, some comments could be more clear, but there are hardly any
comments in wxWidgets that don't help reading the code.

AP> Good code is self documented.

This is a (extremely pernicious) myth. I really don't have time to write a
treatise on good comment style so I'd like to refer you to many existing
discussions about it on the Internet. Let me just notice that code without
any comments simply won't be accepted into wxWidgets.

AP> 6. Consider adopting a standard way of documenting public interfaces.

We do have one, see the files in interface/wx.

Regards,
VZ

Alexandru Pana

unread,
Mar 16, 2014, 9:47:27 AM3/16/14
to wx-...@googlegroups.com
VZ> We did finally drop support VC6 in 3.1 but all this means is that we can 
VZ> now use (most of) C++98. 

That's unfortunate.

VZ> This is not directly related to wxWidgets coding standards. This document 
VZ> doesn't intend to be a general purpose C++ programming style.

I just assumed coding guidelines included this as well. Here is the quote
from the guidelines page: "The second part covers the wxWidgets code 
organization and its goal: to make wxWidgets as uniform as possible without
imposing too many restrictions on the programmer."

 I used the words "encourage" and "discourage" as a way of "guiding" the
well-intended developer to writing more maintainable and readable code.

VZ> And I generally just have no  idea where does this one come from.

I'm sorry, I wasn't aware wxWidgets had switched over to templated
vectors.

VZ>  This is a (extremely pernicious) myth. I really don't have time to write a 
VZ> treatise on good comment style so I'd like to refer you to many existing 
VZ> discussions about it on the Internet. Let me just notice that code without 
VZ> any comments simply won't be accepted into wxWidgets. 

 I have also made a few points about this inside my proposal but you 
haven't taken them into account. I'm not saying comments should be 
completely avoided, I'm saying no comments are good comments. There are
also a lot of talks and articles on the Internet about how comments
should be avoided. To put it simply: if you take a few seconds before
writing a comment to ask yourself why that comment is needed, perhaps
you can change your code or your names slightly to confer that meaning.
I strongly believe this kind of approach results in a much cleaner code,
but everyone has different beliefs and I'm not trying to preach.

Also, even if perfectly self documented code isn't attainable, that
doesn't mean we can't strive to achieve it.

Unfortunately not all organizational comments are consistent. Maintainers
such as "Mike Wetherell", "Vadim Zeitlin" and "Jaakko Salli" have
slightly different comment styles. Also 

VZ> We do have one, see the files in interface/wx.

I meant to say the public interfaces with which the wxWidgets developer
interacts. The ones in /include.

I admit to having written the proposals only shortly after being faced
with wxWidgets internal code, but I still believe discussing them is a
good ideea.

Thanks, Alex.

Vadim Zeitlin

unread,
Mar 16, 2014, 9:55:33 AM3/16/14
to wx-...@googlegroups.com
On Sun, 16 Mar 2014 06:47:27 -0700 (PDT) Alexandru Pana wrote:

AP> VZ> We did finally drop support VC6 in 3.1 but all this means is that
AP> VZ> we can now use (most of) C++98.
AP>
AP> That's unfortunate.

Yes, but the fact is that it's better to have a library which compiles
with both C++98 and C++11 compilers and can be used by everybody than to
have a library that compiles with only C++11 compilers and can be used only
by relatively few of them.

AP> VZ> This is not directly related to wxWidgets coding standards. This
AP> VZ> document doesn't intend to be a general purpose C++ programming style.
AP>
AP> I just assumed coding guidelines included this as well. Here is the quote
AP> from the guidelines page: "The second part covers the wxWidgets code
AP> organization and its goal: to make wxWidgets as uniform as possible without
AP> imposing too many restrictions on the programmer."

Yes, the old document was confusing from this point of view and also too
ambitious and too polemic. I intend the new version to be shorter and much
more to the point.

AP> I have also made a few points about this inside my proposal but you
AP> haven't taken them into account. I'm not saying comments should be
AP> completely avoided, I'm saying no comments are good comments.

This is a very widespread and appealing view which unfortunately also
happens to be completely wrong. My 25+ years of programming definitely
taught me that no comments is never good. This can be seen as an argument
by authority which is generally not very convincing but it's the best I can
do without spending time that would be really better spent on, say, making
3.0.1 release, because you really do need to experience with working with
what started as wonderfully clear (at least in the eyes of the original
author) code base and then went through years if not decades of incremental
fixes and improvements to understand just how valuable the comments are.

AP> Also, even if perfectly self documented code isn't attainable, that
AP> doesn't mean we can't strive to achieve it.

We can and we should. And we also should write comments.

AP> Unfortunately not all organizational comments are consistent. Maintainers
AP> such as "Mike Wetherell", "Vadim Zeitlin" and "Jaakko Salli" have
AP> slightly different comment styles. Also

They're pretty similar though, I think. Of course, ideally they should be
exactly the same.

AP> VZ> We do have one, see the files in interface/wx.
AP>
AP> I meant to say the public interfaces with which the wxWidgets developer
AP> interacts. The ones in /include.

Yes, we do have some (unwritten) rules about those. I'll try to write them
up.

Regards,
VZ

petah

unread,
Mar 16, 2014, 10:03:11 PM3/16/14
to wxDev
On Sun, 16 Mar 2014 14:55:33 +0100
Vadim Zeitlin <vadim-dz6zkcJx...@public.gmane.org> wrote:

> On Sun, 16 Mar 2014 06:47:27 -0700 (PDT) Alexandru Pana wrote:
>
> AP> VZ> We did finally drop support VC6 in 3.1 but all this means is that
> AP> VZ> we can now use (most of) C++98.
> AP>
> AP> That's unfortunate.
>
> Yes, but the fact is that it's better to have a library which compiles
> with both C++98 and C++11 compilers and can be used by everybody than to
> have a library that compiles with only C++11 compilers and can be used only
> by relatively few of them.

It'd be great if you could add some rough guidance about future deprecation rules. F.ex. what's the plan if Microsoft actually stops XP security updates and it turns into a cesspool?

Anything increasing visibility would be welcome, even if it's a moving target.

cheers,

-- p


Bryan Petty

unread,
Mar 16, 2014, 10:12:08 PM3/16/14
to wxWidgets Development
On Sun, Mar 16, 2014 at 8:03 PM, petah <w...@laufenberg.ch> wrote:
> It'd be great if you could add some rough guidance about future deprecation rules. F.ex. what's the plan if Microsoft actually stops XP security updates and it turns into a cesspool?

This is pretty unlikely, and was never a concern with Windows 98 support either.

What it usually comes down to is a combination of a few factors including:

- How many applications still target those platforms?
- How hard it is to maintain compatibility?
- What changes do we need in wxWidgets that we can't support on that
platform? Are they really worth it?

All of those vary wildly depending on the platform, and schedules
outside of our control, so it's not helpful to just pick arbitrary
dates in the future. It's always pretty clearly announced with plenty
of notice when it makes sense.

Regards,
Bryan Petty

petah

unread,
Mar 17, 2014, 1:25:54 AM3/17/14
to wxDev
On Sun, 16 Mar 2014 20:12:08 -0600
Bryan Petty <bryan-Uejh2hED...@public.gmane.org> wrote:
The essence of my question was:

>> Anything increasing visibility would be welcome, even if it's a moving target.

Your first answer seems to say "wx won't change its XP support policy whatever Microsoft decides", and by extension "nor would it raise the lowest-common denominator for compilation" (right?), but your second answer sounds like "we can't provide any future guidance" (plus "don't call us, we'll call you!").

Either way it's useful information for wx users, whether their market depends on the conservative (XP) or progressive (C++11) end.

cheers,

-- p

Alexandru Pana

unread,
Mar 17, 2014, 1:33:58 AM3/17/14
to wx-...@googlegroups.com
What it usually comes down to is a combination of a few factors including:

- How many applications still target those platforms? 

Out of curiosity, how are these statistics calculated? How do you know
the number of applications targeting on each platform?

Vadim Zeitlin

unread,
Mar 17, 2014, 6:32:05 AM3/17/14
to wxDev
On Mon, 17 Mar 2014 03:03:11 +0100 petah wrote:

p> On Sun, 16 Mar 2014 14:55:33 +0100
p> Vadim Zeitlin <vadim-dz6zkcJx...@public.gmane.org> wrote:
p>
p> > On Sun, 16 Mar 2014 06:47:27 -0700 (PDT) Alexandru Pana wrote:
p> >
p> > AP> VZ> We did finally drop support VC6 in 3.1 but all this means is that
p> > AP> VZ> we can now use (most of) C++98.
p> > AP>
p> > AP> That's unfortunate.
p> >
p> > Yes, but the fact is that it's better to have a library which compiles
p> > with both C++98 and C++11 compilers and can be used by everybody than to
p> > have a library that compiles with only C++11 compilers and can be used only
p> > by relatively few of them.
p>
p> It'd be great if you could add some rough guidance about future
p> deprecation rules. F.ex. what's the plan if Microsoft actually stops XP
p> security updates and it turns into a cesspool?

First of all, let me note that supported OS don't have anything to do with
supported compilers, so it's completely outside of the scope of this guide.
Second, I think XP is going to be supported for quite some time yet,
definitely in 3.2. There is not much effort involved in supporting it so
it doesn't cost us almost anything to keep support for it.

Regards,
VZ

petah

unread,
Mar 17, 2014, 10:19:09 AM3/17/14
to wxDev
On Mon, 17 Mar 2014 11:32:05 +0100
Vadim Zeitlin <vadim-dz6zkcJx...@public.gmane.org> wrote:
> On Mon, 17 Mar 2014 03:03:11 +0100 petah wrote:
>
> p> On Sun, 16 Mar 2014 14:55:33 +0100
> p> Vadim Zeitlin <vadim-dz6zkcJxDG0gsBAKwlt...@public.gmane.org> wrote:
> p>
> p> > On Sun, 16 Mar 2014 06:47:27 -0700 (PDT) Alexandru Pana wrote:
> p> >
> p> > AP> VZ> We did finally drop support VC6 in 3.1 but all this means is that
> p> > AP> VZ> we can now use (most of) C++98.
> p> > AP>
> p> > AP> That's unfortunate.
> p> >
> p> > Yes, but the fact is that it's better to have a library which compiles
> p> > with both C++98 and C++11 compilers and can be used by everybody than to
> p> > have a library that compiles with only C++11 compilers and can be used only
> p> > by relatively few of them.
> p>
> p> It'd be great if you could add some rough guidance about future
> p> deprecation rules. F.ex. what's the plan if Microsoft actually stops XP
> p> security updates and it turns into a cesspool?
>
> First of all, let me note that supported OS don't have anything to do with
> supported compilers

True as long as XP is officially supported by MS but when that ends, the last thing they'll want is to promote more XP apps from being released.

>, so it's completely outside of the scope of this guide.

Perhaps it's not the right forum but wx is a platform and as such it'd be nice to get a better idea where it's headed.

> Second, I think XP is going to be supported for quite some time yet,
> definitely in 3.2. There is not much effort involved in supporting it so
> it doesn't cost us almost anything to keep support for it.

It's hard to argue with your carefully-crafted reply (~ "not much effort", "costs almost nothing") but there's no way a resource-constrained project like wx can have it both ways for long (whenever "quite some time" elapsed) because of C++11's uptake. We can tack C++11 features on top of wx and see benefits while we're all still experimenting but over time client wx code will become increasingly divorced from wx's internals, spelling trouble for many reasons.

XP will soon be frozen; ISO C++ changes are accelerating, something has got to give... unless MS does a 180 about XP's termination or C++11/14 is a huge failure and the status quo prevails.

Discuss.

-- p



David Connet

unread,
Mar 17, 2014, 10:17:53 AM3/17/14
to wx-...@googlegroups.com
Which is good, since the company I'm at now (and the one I was at 1 yr
ago (layoffs)) has no plans to drop XP support. Our statistics show a
very significant number of our users are still on XP. (Heck, when I
dropped Win98 support in my wx-based project in 2009, I had a number of
upset users!) (Oh, professionally, we're still using vs2008! Personally,
I've moved to 2010 - and play with 2013)

What I've observed is that Windows (home) users tend to only upgrade OSs
when it's time for a hardware change (usually due to a failure). We're
not like OSX where the OS is deprecated after just a couple years! (my
osx10.5 machine is working just fine, thank you!)


Maybe there should be a note about support commenting the XP will
continue to be supported, even when MS stops, into the foreseeable
future? And when this changes, there will be at least an
N-month/year/version-release time frame from the announcement to the
actual deprecation.

I haven't actually looked for a formal policy, but from lurking here for
a while, I've noticed that when something is deprecated, it takes a
couple of major releases before it actually goes away - complete with
setup.h compatibility flags. Alex, are you maybe just looking for a
formalization of that (as opposed to a 'we will drop X on Y')?

Dave

Lauri Nurmi

unread,
Apr 2, 2014, 3:27:52 AM4/2/14
to wxDev
On Mon, 17 Mar 2014, Vadim Zeitlin wrote:

> Second, I think XP is going to be supported for quite some time yet,
> definitely in 3.2. There is not much effort involved in supporting it so
> it doesn't cost us almost anything to keep support for it.

Will it be the same kind of support as with 3.0 and Win9x currently:
nobody(?) actually tests anything on Win9x? And nobody even deploys
software for Win98 using wx 3.0.

LN

Vadim Zeitlin

unread,
Apr 2, 2014, 7:37:39 AM4/2/14
to wxDev
On Wed, 2 Apr 2014 10:27:52 +0300 (EEST) Lauri Nurmi wrote:

LN> On Mon, 17 Mar 2014, Vadim Zeitlin wrote:
LN>
LN> > Second, I think XP is going to be supported for quite some time yet,
LN> > definitely in 3.2. There is not much effort involved in supporting it so
LN> > it doesn't cost us almost anything to keep support for it.
LN>
LN> Will it be the same kind of support as with 3.0 and Win9x currently:
LN> nobody(?) actually tests anything on Win9x? And nobody even deploys
LN> software for Win98 using wx 3.0.

I obviously can't promise anything, but I think XP is still much more
relevant now than Win9x was at the time of 2.8 release. There is also a
huge difference between supporting Win9x (no Unicode!) and XP (which just
lacks things added later but not in any kind of fundamental way). So I
think it's not going to happen in the same way. But again, it's not any
kind of a promise, if you really need XP support the best you can do is to
test it yourself.

Regards,
VZ
Reply all
Reply to author
Forward
0 new messages