The 5 Pillars of Successful Software Development

courtesy tome213

“…If I have seen a little further it is by standing on the shoulders of Giants.” – Isaac Newton

It’s Friday afternoon and what a long week it’s been! You’ve worked solidly since Monday morning, plowing through code each day from 8 – 6, following up calls and emails, attending meetings and in-between, working your butt off. But then you remember that at lunchtime, the project manager came in and said that a last minute feature had been agreed upon and it had to go out today – no compromises.

You didn’t like it, but well, it wasn’t your call to make or break.From your window you can look down on the bar next door. The music sounds phenomenal and the crowd’s growing fast. It’s looking like a great night out tonight. Hey, wait, they’ve just announced that the drinks special is going from 5 – 10, not the usual 5 – 7. What a night to get amongst it with mates after a hard week.

But there’s a problem; The feature that the project manager agreed to wasn’t just a “little fix” (how often have you heard that line?) It might have been, if the code was documented or self-documenting or you had any project documentation. You don’t care what form it comes in, be it in a Wiki, Word/OpenOffice docs, text files, damn anything! But there isn’t anything – nada.

Wait, let’s just ask one of the other dev’s about it – that’ll sort it out. Oh, wait, you did that already – but no one know’s anything about it. The only other dev that worked on it landed you in this mess and he doesn’t work here any more. What’s worse, it’s Friday night and everyone else’s gone home. So it’s just you with no clear end in sight – watching people next door have a great time, wishing you were there. Sound familiar?

Now situations are not always as bad as this, but they can be equal to it and worse. From the early days of coding, to Uni days to beyond, we’re preached the mantras;

• Document your code
• Make it self-documenting
• Keep good project documentation

Excuses, Excuses, Excuses

How many times is it actually done?How many times do you do it? How many times have you heard or thought the following things?

• I don’t have time to do that
• It’s not my job
• There’s no scope in the budget for it
• The client’s not paying for it
• It’s not really important – you’re an ace developer (you’ll pick it up in no time)

Personally, all of these “reasons” are complete and unadulterated rubbish! They’re are not reasons, at best they’re excuses and nothing more. Well, maybe, they’re ok if it’s not you that will have to pick up the slack, if you’re happy with being in the situation described above instead of being:

• Out with friends
• Home with your husband/wife/partner and child
• Running in the park (or at a great BBQ)

If you’d rather be coding unnecessarily, then sure, any of those excuses are vaguely ok. In every other case, they’re not! End of Story Still unconvinced?

The Costs of Poor Documentation

• Time required for the original developer to remember how something works, days weeks or months later
• Time for new a brand new developer to the project, to figure out how a section works, when the original one, or carry-over maintainer, is no longer around or unable or too expensive to be contacted
• Loss of face when projects repeatedly run over
• Loss of reputation when you deliver rubbish or have to keep stalling or postponing a deadline

All of these things cost, either directly or indirectly. Now yes, sometimes it may seem like a drudge to write documentation and not write cool code; but then testing can seem like a chore, but you don’t skip that; do you? It may seem like an unnecessary task, but it needs to be done. If you’re a professional developer you know this.

Solving the Situation

So what do you do? Only five things are needed, what I call, The 5 Pillars. Expand on them if you will, but the essentials are:

1. Project documentation
2. Self-documenting code
3. Inline code documentation
4. A coding standard
5. Auto-generate documentation

Project Documentation

Whether in the form of API and specification documents, a project wiki is a must and so readily available. Two of the best ones around are Trac and Redmine. List in it:

• Project contacts
• Notes of meetings
• A compilation of email correspondence
• Integration documents

Basically, put in it everything that you can get your hands on. This step is vital! The original people may have moved on, but this will give you and your team essential information on what links to what, error codes and messages and and idea of why decisions were or were not made.

Self-documenting code

Now it makes no sense to document every class, method, variable or line of code. That’s just lunacy. You also want to minimise the need to actually write the documentation. So don’t use magic variables and don’t name variables that make no sense. Consider the following:

• $a, $j, $k
• $array
• $list
• const int TWENTY_EIGHT = 28 – (courtesy of Bad Variable Names)

No one will know what they mean and you’ll need with wisdom of Solomon to figure it out. Secondly, as Lang Sharpe says over on The Data Asylum, don’t use double-negatives and don’t be vague about your intent. I won’t re-hash his excellent article, except to say, make your code clear and discernible.

Inline code documentation

Now I know that I said it’s not necessarily always required, but if something is unclear, then document it. Use the full complement of phpDocumentor tags and run it as part of your build script. If you borrowed code from a site, reference it with @see, if there’s a link to a site with better information that you can or have time to write, link to it with @link.

If a variable’s oddly named, but required, use @param and give a good, but concise description. If a method’s superseded, add @deprecated in the method comments. Alternatively, as Rowan Meerwood suggested in his excellent talk on Living with Legacy code, take a strategic approach to building a structure around the legacy code so that it can be better managed and migrated. Aim to understand the concepts and motivations and catalogue the live platform, code and environment. Don’t leave it for someone else.

Develop to an accepted coding standard

I work to the Zend Framework coding standard, as I’m a bit of a ZF nut; but even it’s based on PEAR. Now like it or hate it, professional coding standards are the right way to go. They enforce that everyone writes in the same style. If the style’s bad, at least it’s consistent and clear for all to read. You know what to expect and that lessens the impact on you and in turn, your impact on everyone else.

Auto-Generate Documentation

Now take the hard work on a coding standard and code documentation a step further. Update your build server to automatically generate api docs for your team. This will then encourage everyone to write better documentation as, if you’re using a good IDE, it will pay off in spades as, when you inspect a method, the IDE tells you what the method’s for – saving you time later. Don’t have a build server yet? Have a look at Phing or Jenkins. Both are straight-forward to work with and configure to your needs. Less guessing, less time-wasting = more productivity.

So what are you going to do?

You can either be in a vicious or a beneficial circle. You can be spiralling hopelessly down, or standing on the shoulders of giants. The question is, where would you prefer to be? When you’ve decided, I’ll have a Glenmorangie, neat, thanks.

But enough from me, what do you feel? What’s your absolute worst experience that you’ve had? How did you resolve it and what did you do to stop it hitting you like a freight train again? I’d love to hear about it. Let’s compare notes.

• Bio
• Latest Posts

Matthew Setter

Matthew is a freelance technical writer and technical editor and regular contributor to a number of tech publications, including PHP Architect, PHPMaster, CloudSpring and New Relic. When he's not contributing there, he's writing content here on Malt Blue. What can he say, he's an avid technical writer and software developer. Get in touch if you want awesome, up to the minute, technical content for your blog, business or publication.

Latest posts by Matthew Setter (see all)

• Zend Framework 2 – Hydrators, Models and the TableGateway Pattern - 05/15/2013
• Use RouteMatch in Zend Framework 2 For Easy Routing - 05/01/2013
• Why Testing Makes a Project Successful and You Can’t Afford to Deny It - 04/23/2013