thoughts on code quality and sparks (or : the good, the bad and the ugly)

In my seven years of being a developer I have seen quite a few pieces of code, some of which were great works of art, while others were what could only be called a pain in the arse (written some of these myself).

There are many good-coding-dogmas, many design pattern catalogues and, I'm pretty sure, at least one best practice implementation for each problem you face dug in the depths of the internet. It's not always easy to find, though: In a recent search for documentation on IBM.XMS for dotnet, I was desperate for a few days, until eventually I ended up on an IBM-MQSeries board where people would try and help. The manual delivered with the XMS-lib was basically an API-doc and the sample applications did not compile. The solution was later found : Some assemblies had to be added, but no-one really knew why (or has written it down)

For a developer, a project starts somewhere in a meeting room, as a sheet of paper on your desk or, which is most enjoyable, as a spark in your brain while you are doing something completely different (the former cases just mean somebody else has had this spark).

So, whenever you start a new project, you basically face at least one of those thoughts:

• how to get it done?
• can I reuse what I have already coded?
• how can I get it over with really quick?
• how can I produce good code (that I might reuse later)?

It's a person-thing as well as a project thing. If a project demands quick delivery and leaves no time for design, you can be conscientious as you may, but your only ticket to success is a quick solution. The resulting code is often ungeneric and proprietary. But If a project has a more generous schedule, the shores of good and bad coders will diverge. Bad coders will code whatever comes to their mind after forging up a general battle plan. Good coders will spend some more time and go into detail regarding classes and processes or sometimes writing generic frameworks. The danger lies in over-designing things (like implementing a complex pattern where a simple class would have done). Time and again, there are software architects who do the conceptual work instead - a draft with very little understanding of "real-life" implementation problems.

So, What makes code actually good?
First of all, it must be understandable. This can be achieved by using standardized design patterns, but also by "humanizing" code. The target should never be to gain maximum complexity, but rather maximum simplicity. Second, good code is documented. It's not negotiable that some snippets end up being rather complex, hopefully because some things just can't be done in a simple way. Having a documentation (again, human readble) can be a great deal of help in such situations.

And although real beauty also comes with the language you code, it is possible to write some really good stuff with not-so-great languages. I remember the perl daemons designed by Marcus (hi Marcus, please ignore that thing about not-so-good Perl ^^) at sipgate - pure beauty in a language that isn't famous for its OOP capabilities.
Recently, in search for a specific solution, I checked a project done by another coder. Looking at what was done, the coder had programming and abstraction skills that surpassed mine by some length. But all those tiny sparks he's had when coding it just wouldn't leap over to me: there was no guidance through the code, no wiki entry, no inline documentation. after 2 hours of failed attempts, i quit it.

And what makes code bad?
Spaghetti code (not just top-down, but also all-across), lack of documentation, lack of human readability. Anything that shows the coder hasn't loved what he was doing. What good is a highly functional library if no-one knows how to use it? I think this does not need further saying, some of the stuff mentioned above is about bad code as well. Although, just to get rid of this, the most disastrous thing I've had to work with was (also written in perl) a daemon that had functions that spanned over more than 11 full pages. the actions taken were, each one of them, simple and understandable, but the amount of repetitions the absolute lack of documentation in it made me slam my head on the table and deeply doubt in the existence of gods. As pratchett said : "artifical intelligence is beaten by real stupidity every time". He's just so right about that.

Who am I to judge?
A developer, a user of APIs, a resumer of projects other people started. Some other things maybe, but last but not least a human.

What I want to say is: we live and learn. While living can't be helped (it happens more or less automatically), we have a lot of influence on our learning. And that is what we need web2.0 for : a more practicable way of sharing our sparks, the community must pull together more closely. Good code can be less shiny but still gold, if only it's imparted in a helpful way.

take care