25 September, 2007

Write Source Code for Other Developers, Not the Computer.

I’m not sure as to whom to attribute the following statistic, but i believe it was something along the lines of this;  Code is read vs. written on at a 10:1 ratio, meaning that the is far more reviewing of any specific codebase than there is writing to said code.  Furthermore, the majority of software positions involve maintaining and modifying existing code as opposed to creation of new code from the ground up.

To what does all of this allude?  The importance of writing clean code.  Knowing full well that other developers are going to have to read, understand and most likely modify your code in question at some point(s) in the future.  This is where our responsibility as software professionals (even in the case of hobbyists) comes into play.  

Several languages have tried to address this problem by intrinsic design decisions.  Most notably among those in recent times are Java and Python.  Java does so by its explicitness by design, and Python by its forced formatted a la the whitespace requirement.  Both are effective in what they do, however there are still a multitude of ways in which both can be written in a harder to read format.  Obviously choice of variable, function, class and object reference names is a very large point of readability (or not) which really cannot be enforced by a language specification.  Let us take a look at this very issue and while we’re at it, i’ll be clear that this is not a Python vs. Java issue discussion.

All too easily so many coders (I know this from having had to look at, understanding and refactor their code) overlook one of the best sources for building readable code, and that is their naming convention.  There have been several best practices and coding style specifications documents produced that one might think me as flogging a dead horse, but I assure you this is not the case.  

In the following examples we see a variation of languages and how we might commonly see the same variable name referenced (and initialised as it were):


num_of_doors = 4 ;


numberOfDoors = 4    OR    numDoors = 4    OR    number_of_doors = 4


numberOfDoors = 4;    OR    numDoors = 4;    OR    number_of_doors = 4;

Java, C#:

int numberOfDoors = 4;    OR    int numDoors = 4;    OR    int number_of_doors = 4;


number-of-doors := 4;

C, C++:

int intNumDrs = 4;    OR    int num_drs = 4;    OR    int int_drs = 4;


my $vzoiuwriozufsd = 0x04;

The point here is that there are many varied ways in which the same variable can be referenced.  I am of the opinion that much along the lines of Guido van Rossum of Python (and to a lesser extent ABC) fame, that there really should be one and only one obvious way to do it.  This isn’t to say that I think everyone should code in the same language, and speak the same tongue, etc.  What it does mean though, is that to be understood by others (and sometimes by ourselves), we need consistency, and unless we have a set of strict guidelines set out for us as software engineers, developers, etc., we might as well code in our own made up dialects.  

I am of the opinion that a proper interpreter, compiler, virtual machine, etc., should be more than capable of quickly turning long variable, class, function and method names into concise tokens with small internal footprints.  So much to the point that there is no excuse for not being verbose.  At one point in time, every single byte of allocated memory for names of the aforementioned items was a crucial issue which required extreme concise naming conventions to be followed.  Those times are gone in this day and age, allowing us to be clearer and more expressive.  

I can see using single letter counter variable names, but never could I imagine naming a class, method or function in such a sparse manner.  I like to think that clean code reads somewhat like a choose your own adventure book, were it to have a greater variety of options available.  Functional or Object Oriented is immaterial here, as cleanly written code isn’t tied to a specific construct or paradigm.  I think most of the following rules are applicable to pretty much every language out there.  Emphasis below pertains to items that I feel are not language specific guidelines.

As can be seen, most of the above are applicable to languages other than Python.  I find myself at my current place of employment having to deal with the problems for which this list addresses.  Much of what I’m doing is updating a legacy code base that is literally plagued with dozens of individual programs and modules that are blatant attacks on decent code.  They (collectively) single-handedly break most of the above guidelines.  

First off it is almost entirely written in perl, which instantly shoots down the Readability counts factor (and no, it wasn’t done with the strict pragma, and yes it uses a bunch of requires and plenty of global variables).  

Secondly, errors don’t pass silently because there is no built-in exception handling in perl.  Evals of code blocks does not equate to a proper exception system, nor does an add-in module.  Exceptions are something which need to be a core part of the design of the language, and perl falls far short of the bottom of the heap on this issue alone.  

Thirdly, when one is expected to maintain code in an environment wherein the expectation is to follow the existing coding schema as it were, with global variables, no exception handling, etc., it truly becomes a daunting task because one must force his/herself to think ‘wrong’.  The logical and/or proper solution that is naturally though of as a solution would only lead to reprimand, simply because trying to think in such a manner will produce mistakes, primarily because trained seasoned professionals don’t think in the same manner as the less experienced coder(s) responsible for the legacy code int eh first place.

Finally, (I’ll leave it to three to be nice to those few perl hackers who’ve read this far), after ten plus years of coding in perl, I’ve come to learn that the TIMTOWDI (There Is More Than One Way to Do It) mantra of perl is one of the biggest problems that arise from the language.  It is this careless and dare I say reckless mindset which has led to so many atrocities in the professional coding world.  

My point is simple enough to follow.  Write readable code, as it is a defining factor as to how far you’ve matured in the field of software development.  It doesn’t necessarily mean you are even that good at what you do, but what it does do is show how you understand a rudimentary problem that so many others have failed to realise.  Readability Counts, and without it, we are truly lost.  

15 September, 2007

Why projects fail, or more appropriately why QA cannot be an afterthought in the software cycle.

Over the years I have been in a multitude of software development environments, and bar none, the biggest reason as to why software projects fail can be overwhelmingly attributed to quality assurance.  More precisely it is either the complete and utter lack of a QA process (let alone a team), or simply the absence of sufficient testing procedures. 

Quality of software isn’t simply the fit, finish and packaging.  It is a whole encompassing methodology through which the program(s) involved are designed, revised, (when the time comes) patched, and upgraded.  It has been a long held observation of mine that coders in general don’t think of QA for several reasons.

    ◊    They feel that their programs were well designed and that they’ve accounted for all scenarios.

    ◊    The program(s) is/are too short to possibly have any error(s).

    ◊    They can be their own quality/testing department.

    ◊    They can/have figure(d) out all the necessary permutations of possible interactions that user(s) would possibly consider entering.

    ◊    There is no budget, nor push for a proper QA department and/or QA procedures.

While the above is a very, very small subset of all the possible reasons that I’ve seen/heard, the reality of it is that these are being given as actual excuses when confronted about what QA processes are in place.  The reality of it is that there are a lot of substandard, unprofessional software developers out there, who despite all the best practices of established community acknowledged developers and software engineers, continue to believe that it isn’t worth their time.

The outlook is sadly very grim from where I stand.  All too often there is considerable resistance from management, and more so from other coders when the topic of writing tests first, something we have been reminded of recently from (most notably) XP and Agile development circles.  Managers don’t want to waste time on a tight deadlined project writing code that will never make it out of the door and to the customer(s), and other coders in so many situations feel it is boring and unnecessary.  

The reality of it all is that those mentalities doom its transgressors to a endless of cycle of bug chasing and failure.  The impression that the end-user/client receives of a given software firm/group/coder is based almost entirely on the quality of their work, but there simply doesn’t seem to be the necessary forethought by those responsible to make the decisions toward quality.  

Quality isn’t simply a department which points out and/all flaws in a product, and quite frankly shouldn’t be taken as such.  Coders, particularly bad ones despise a proper quality arrangement because it points out all of their flaws without ever really providing an equal amount of praise.  Developers as a whole like to hear positive affirmation about their work.  The code produced as, such as an artists, an extension of their being, and thus hearing about problems with their work, they all too often take it personally.  They see it as an attack on their character, and that which makes them who they are.  This is something I would expect of a child, but not a professional.  

It doesn’t have to be this way.  We as a collective group of software developers, engineers and architects are the ones responsible for ensuring that quality of not an afterthought.  We have to make it a priority to build quality into ever facet of not only our software, but every facet of our varied processes.  The size of the application is immaterial.  Whether a simple shell script, or a half-billion lines of code suite, the same level of attention to quality is a pre-requisite for success.  

This includes the planning process as well.  Writing tests before actual code is produced is wonderful, and needs to always occur.  This requires discipline, which many seem to lack and/or overlook as a legitimate need.  It goes further than that though, all the way to the planning stages.  What is the point of having a high quality-focused mindset at the code level, if the project itself is lacking the same on so many other levels. 

We need to demand this mindset from the get go.  It is our responsibility to ensure that the necessary practises are put into place from the beginning, because no one else is going to care, let alone take the initiative.  If you take pride in your work, you need to ensure that it does as it is/was requested, and that requires the right methodology as well as mindset.  Not to imply that our lives depend upon this, but in reality it does.  

It isn’t as if all of this effort isn’t without reward.  We need to teach the next generation of coders to start with quality as their foundation, and it will simply become a ubiquitous piece of the process.  The benefits of this holistic view are many, and among them are:

    ◊    Stable code

    ◊    No surprises

    ◊    Happy clients

    ◊    Time to work on the next big thing (tm)

    ◊    Less stress

    ◊    Future business

    ◊    Peer appreciation

Quality is everyone’s responsibility, and that means it has to start with each individual, no exceptions.  So if you, or others which fit the bill as prescribed above have hangups on this issue, then it is time to think long and hard about it and either hangup your coding chaps, or take that next step and better yourself in your field, kicking your credentials up a notch, by having a quality centric mindset.

In future editions of the codedevl.com journal, I will be taking a more detailed look at each of the phases of the quality aspects of the software life-cycle.

11 September, 2007

It’s been a while... I’ve been busy coding away. Here’s an update.

    I’ve been rather busy recently now that our beta version of software where I am employed has made its way to production.  Since that has transpired, all of our Trac entries can be attacked in a more systematic manner.  Here’s a little rundown of what I’ve been doing.

    Handling my son’s integration into his newest school year endeavour, as well as my wife’s into hers.  She just completed her masters degree and is starting her second year (first full year) as a teacher of Biology..  to kids born the year that she and I graduated (together) from high school.

    Creating the backlog of CodeDevl.com podcasts, and editing.  I never realised exactly how much time it takes to edit a podcast recording.  For every five minutes spoken, there are ten minutes spent editing and cleaning up.

    Learning and implementing GIT version control/repository software at our place of employ, as well as my local network as a replacement for Subversion (SVN).  

    Wrote a python (base classes pure) application which handles all migration of beta software to both the GIT repository paths as well as handling moves to production (including automated changes to certain header includes).  I’m rather happy with this application as it has saved many issue from transpiring.  Due to the haphazard manner in which some of the code base is arranged (particularly the beta vs. live paths), problems can and have occurred, hence my reasons for taking the initiative to create said program.  

    Additional work with re-learning Java, and keeping current with other technologies (Python 3K/3000/3.0), Javascript, Ruby, Smalltalk concepts and to a lesser degree Lisp (not including additional emacs functionalities).

    I do promise that I will be continuing to update both this written journal as well as the podcast site, and just wanted to let those reading that I have not dropped off the face of the earth, just immersed myself back into the changing flow at my workplace.