No Comment

There seems to be a push towards not commenting code, with the general argument being that if your code needs commenting, it is too complex. I kind of agree with the sentiment here, code that is tough to comprehend is bad, but I think this is an oversimplification.

In my experience, at the point at which we are writing the code, we are terrible judges about what is too complex. Things we think we will be obvious to anyone [including the new person, straight out of uni] reading through the code turn out not to be obvious, not even to us – six months later when we are trying to track down the cause of a bug in said code.

There is a secondary argument, that comments are not always accurate, because…

The author of the comments has described the intended functionality of the code, but this differs from what it actually does.
The comments may not accurately describe what the code *is* doing, but they might neatly explain what the developer *intended* for it to do and that could be very useful information when you are searching for that oh so elusive bug.

The comments have not been maintained in line with the code and are now stale.
People don’t always do the right thing because reasons. Expect the bullshit but never accept it. Do code reviews; include the comments in the review.

If you find yourself writing comments like “Increment counter”, you should stop. If you have contrived to produce some horribly obfuscated, overly templated, pointlessly typedef’d hell that requires a comment the length of War and Peace to justify, you should be stopped. But if all you want to do is try and give a helping hand to the next person, get to it. :)

I am still learning. I hope to carry on learning forever. I might well be wrong about all or some of these things. I might change my mind on them in the light of more experience, or different arguments. I am totally okay with this.

So Fresh, So Clean

Once upon a time computers were slow. Really slow. Software developers had to make a really concerted effort to optimize their code, seeking to use as few CPU cycles and as little memory as possible, today’s developers are spoiled in comparison. I am genuinely grateful that the guys who took me on after University taught me the difference between writing code and developing software, that they took the time to show me why there was so much more to it then getting stuff to build and run. These days I am responsible for putting potential new recruits at $place_of_employment through their paces with a C++ test, and as much as I’m looking for working code, I am also looking at coding style and often find myself saying things that were once said to me (I guess it’s kind of like finding yourself complaining about your kids music like your Dad used to do). I never cease to be amazed at how people with apparently years of experience can produce answers to such simple questions that require me to sit and analyse each line for minutes at a time in an attempt to try and uncover their secrets.

My penchant for clean code is a gift and a curse though. I was genuinely startled to be told by a fellow developer that code efficiency was something that embedded software engineers needed to worry about, but not us!?!

Satisfaction is the death of desire.

QSpacerItem: Stretched to breaking point

My days of using the Qt Designer application have trained me to define all QSpacerItems with a size hint of 1 by 1, a habit that I’ve yet to drop even though I no longer use Qt Designer. This week I was working on a GUI which requried a large horizontal spacer, around 2000px, but I could not get QSpacerItem to behave the way I wanted it to, it would stretch so far across the screen and then just stop. Long story short, it seems that QSpacerItems will only stretch so far beyond their size hint – defining the width of the size hint to 10000px resolved the problem. Virtual fist bump to El Jefe for having previously suffered this problem and remembering the fix. (Qt 3.3.8)

public class FakeButtonFrame : public QPushButton

So today I found myself fighting against the short comings of Qt 3.3.8, I should point out right from the off that I am fully aware of the existence of Qt 4.5.x (Mr Pandy is performing a port to 4.5.1 as I type), but for the project I was working on I had to use 3.3.8. I wanted to draw some QWidgets on to a mainly black, but multi coloured background without losing the nice curved corners. I am sure some of you are thinking that this sounds easy, but it is not as simple as you think. Qt 3.3.8 doesn’t support transparent backgrounds; the way in which the curved corners are achieved in standard Qt 3.3.8 GUIs is to ensure that the background colour of the widget matches that of the widget it is being placed on to. Setting the background colour of the widget to black worked for the most part, but not for the non black parts of the GUI where the black pixels in the corner of each right angle alerted everyone to their presence.

I subsequently discovered the real kicker to this conundrum was that only QPushButtons support foreground and background colours properly, meaning that the background colour trick did not work on the other widgets: they turned completely black. My frustration at this point was reaching fever point  and my sighs were audible enough for El Jefe to hear them and ask me a question that still leaves me horrified, “I wonder if you can you add widgets to a QPushButton?”. I could see what he was thinking, but I didn’t like it… surely it wouldn’t work… but it did… sort of. The fact that a QPushButton is a QWidget meant that adding a layout and widgets to a QPushButton was cake, creating my own subclass of QPushButton with a custom method to eat any mouse events ( virtual void nomNomNom( QMouseEvent* e ) ) was cake too, but preventing the button from responding to mouse overs like a QPushButton was not so easy. I disabled the button to prevent it from responding, performed a switcheroo on the active and disabled colour palettes, compiled, ran the code and discovered that disabling the button had Haitianed it – it had forgotten how to perform the foreground-background trick and  it turned black too!

QString::null WTF!

I recently discovered the cause of a bug feature in some software that I wrote (Qt 3.3.8) and thought that I’d share the information since it feels like the sort of thing that lots of people might have done. Essentially, the problem was my assumption that QString::null is some sort of special value, it isn’t, it is just a reference to a static empty QString. Given this information, consider the following three QStringLists:

QStringList listOne = QStringList();
QStringList listTwo = QStringList( QString::null );
QStringList listThree = QStringList( "" );

If, like me, you assumed that QString::null was a special null value, then you might reasonably expect both listOne and listTwo to be empty QStringLists and listThree a QStringList containing a single empty QString. The reality is that listTwo is actually equivalent to listThree, so when you are tearing your hair out trying to work out why your nice empty QStringList has a length of 1, remember this post. You have been warned.

It is worth noting that QString::null has been deprecated as of Qt4.0 and calls to it now evaluate to seperate calls to QString(), I guess I wasn’t the only person that fell into this trap! I know that assumption is the Mother of all fuck ups, but I can’t help thinking that this could have all been avoided by naming it QString::empty instead.

The great parenthesis debate

Appetizer:

The coding standard where I work dictates that the return type should be on a separate line to the rest of the function header, for example:

void
Foo::doStuff()

and not

void Foo::doStuff()

I have yet to discover why this is, but I quite like it. However, the situation with the brackets is rather different.

Main Course:

The standard says:

if ( true ) {
// Do stuff.
}
else {
}

Which I can live with, but I prefer the following method as I think it shows more clearly where blocks start and end:

if ( true )
{
// Do stuff.
}
else
{
}

However, this last one makes me want to vomitseen not just at ASL, but at other places of professional coding:

if ( true ) {
// Do stuff.
} else {
// Do something else.
}

Yuk!

++C

When I graduated from university I wasn’t naive enough to think that I was a complete Software Engineer, however, I didn’t appreciate just how little I really knew about programming in the real world. I can only liken it to learning to drive. Driving instructors don’t teach you to drive, they teach you to be able to make a car go and stop, you don’t learn to drive until after you get your license. Programming is the same, when I left university I knew how to write code that would compile and run, but the code I was producing was poorly commented, inefficient, wordy (i.e. not dry) and…well, you get the idea. The best example I can think of is the postfix/prefix increment operators. When I joined my first company, every for-loop that I had ever seen, or written, had always used “i++”. The guys at work were quick to challenge this, they asked why I used “i++” instead of “++i” – considering the latter is at least as efficient as the former*. My answer was that I didn’t know and had never really considered it. Two and a bit years later and I am now just as passionate about keeping code dry as the people who challenged me at work.

Some companies will not hire graduates for the simple reason that they will have to put them through the same initiation that I experienced. This seems a tad unfair on the graduates, even if it is a sensible decision to take. I think that software companies should have a greater part to play in shaping graduates, because at the moment things are tailored to the universities e.g. the incredibly verbose commenting style that makes it easier to grade a squillion reports in a couple of hours. Chris, if aworka doesn’t work out, maybe you can start a course called “Programming in the real world”!
*Some compilers will evaluate “i++” to the same as “++i” if the return value is not used.