Let me begin with introducing myself, my name is Ali Mosavian, I am Software Engineer at Mobile Sorcery and head of Linux platforms. I've been into software development seriously for around 11 years now and done pretty much everything in this field. I started out in QBasic and learnt to program by using the "online" (as in, in-editor) help. That was a wonderful language/tool, but the problem was that you couldn't actually create compiled executables. So when I discovered QuickBasic 4.5, which could actually compile code, all my programming problems were solved, or so I thought. Pretty soon I discovered that it was really slow. You see, in interpreted mode, the code was.. well interpreted. Even though there was a lot of self modifying action going on in the background, it was a lot slower then compiled code. And the compiler that came bundled, generated horrible code, even by 1980s standard. So I decided that something had to be done. QuickBasic had something called CALL ABSOLUTE, which called an absolute address and started executing from there. So what a lot of qbasic coders did at that time was to write machine code for different things, such as rotating an image, and used call absolute. But this was just too ad-hoc, too much of a hack for my taste. I wanted to do it properly. So I decided to write new libraries that where properly designed, that is, very simple but not crippling, powerful, extremely fast and consistent in everything. So I learnt assembly programming, and did that. This helped, I could now do things such as quake one map renderer in quickbasic. But it didn't really do anything about 640 KB memory limit, so I decided to write a new compiler for the language. So I learnt C and C++ and wrote a new compiler. And so on, in the DOS days it used to be challenging to program. You had to do most things yourself, on a low level. But later on, with operating systems that actually worked (yes, unix has been around for ages) with lots of abstraction layers, GPUs and so on, it just wasn't the same. And after working at a few companies which did not have anyone that knew what they were doing, my interest in software development pretty much faded away. During my Masters I came across a field called machine learning, an extremely interesting field. So I decided that's where I'm going to stay and do research. By accident however, I discovered Mobile Sorcery, which seemed to be doing all the things I used to love about software development. Creating innovative things at a low level, compilers, recompilation etc etc. So I decided to give software development a last chance, this time it was different however. Everyone at the company were very talented, and the best management an employee could have. Yet the atmosphere was very relaxed, and your work makes a difference. And that's how I ended up here. I am a big fan of doing things properly, properly thought through, with proper architecture, documentation and consistency, thus, I dislike ad-hoc solutions and hacks. In the long run it always a bad deal, always.

So how come no one ever wants to do things properly? I guess a common argument is that it takes too long, or maybe the it'll end up slower. And as we know, software engineers always have too little time. I strongly disagree with this. In software, you always end up paying for every line of code you and everyone else, have ever produced. This is a common but yet often ignored fact in this industry. For anyone starting out as a programmer, it doesn't take long before they discover that, that piece code that was so-trivial-that-you-did-not-even-bother-to-write-in-human-readable-form, yes, you know what I mean, the one you thought you'd never have to go back to, it's back! And with a vengeance! And now you're spending hours scratching your head, wondering what the hell its doing. So a few hours later you know exactly what it does, but it calls 30 other pieces of code that's even worse. And now you have to figure this recursive mess out. You probably get the picture, except, when you work in a team, you have to spend days instead, figuring out what that recursive mess does, because you didn't even write it in the first place! People figure that, if they write it ad-hoc, they'll save a bunch of time, which they don't have enough of in the first place. But this is false logic, because ad-hoc solutions only work in specific cases, which they were meant for. But software have very long service life. During that time they have to continuously be worked on, to add new features to keep up with new demands, to fix old bugs, and lets not kid our selves, all software has loads of bugs, well tested software just have harder to detect ones. They will eventually show up, and they will probably be even harder to fix. What is my point? You might be happy that you saved a bunch of time with the "clever" ad-hoc solution, but in some time you'll have to add new features or patch "bad features". This will add yet another hack, and yet another hack, and a few more hacks to fix some bad hacks, then a few more hacks, and of course more hacks to fix some other broken hacks, and the circle goes on. This will exponentially grow into a tangled mess that no human can understand, and each fix or each new feature will waste more and more time, especially as time goes on and no one remembers anything at all about what the mess was supposed to do. Now, had that same developer taken a few extra hours, to create a consistent architecture for his solution, and think about how it might need to grow in the future, each new feature had taken very little time to develop. And it would still be clean after 10 years of shelf life. And as for proper solutions being slow, well, there simply is no logic behind that. Even back in the 1960s, engineers knew that generally, 90% or more of the execution time of software is spent in very very small parts of the code. And that is where it matters, and only there.

That brings me to my next subject, documentation, every one knows you need to have it. But no one will do it. Again, this is the result of inverse logic... a common argument against documenting is that it takes time, and we don't have it. Well, some day you'll have go back to that code, and that day will be a complete waste of time. Why? Because that time is wasted on trying to figure out what the code did, but that's not all, all code, except for strict functional code have a lot of side effects, and those are usually much harder to figure out then just what a piece code does. Who hasn't ever changed a tiny bit of code to discover that nothing works any more? Well, that's side effects, and if these aren't properly documented, a lot of time will go to waste in the long run. And trust me, there isn't such a thing as self documenting code. No, really, there isn't.
So what is well documented code? Well, first of all, it shouldn't be written for the compiler. The compiler can parse anything, as long as the syntax is correct. It doesn't care what the code looks like. Those who matter are other people who will read it. Always write your code for an audience, and always write doxygen/javadoc like pre header comment above each class, each method, each function. These should state what it does, what the parameters are, what limits they have, return values, exceptions, side effects should be documented and possibly pre and post conditions. This sounds like a lot, but it really isn't. You'll save yourself and your co workers a lot of time in the end. Not to mention that your co workers will be a lot happier. General comments in functions/methods which explain complicated parts are great, but if your function/method is long and complicated, you should consider splitting it into smaller parts and try keep every method/function minimal and simple. It works remarkably well. And yes, comments do get outdated, but it is up to you to try your best to keep them updated. Even if outdated, it's still much better then no comments at all. So how do you know when you shouldn't comment? My philosophy is that there is no such occasion, once you start deciding what needs comments and what doesn't, it easy to push the limit farther and farther.

Other tips, prefix all class fields with m_, this makes it much easier to understand code once you get used to it. Because you will know exactly which "variables" are class fields in every method, and won't have to scroll up and down all the time. My last advice, cramming everything into a few files will not make everything go faster or be more compact when compiled. Please do not do that, its a recipe for a headache.

Here's one example of okay code http://code.google.com/p/mosync/source/browse/MoSync/trunk/runtimes/cpp/...

Hopefully the world can now start producing better code ;)