Tag Archives: Development

How not to become the maintenance developer

As a developer it seems, you always seem to strive towards producing ever more complicated code. Utilizing new frameworks, adopting an ever evolving “convention before configuration”, pushing object-oriented programming – maybe Domain Driven Development – are practices introduced, refined and explored in the quest to prove yourself as a steadily better developer with rising skills.


Yet to what point?

While the intricate complications may impress fellow developers, doing so often digs a hole which may be pretty hard to get out of. Every complication – not matter if it is in the design, the architecture or the structure of the code – often provides the opposite effect of the desired outcome. The whims of your current self to impress developers with the latest fashionable technique, is short termed reward for a long term pain.

I accept some fashions and whims do change and solidify to become better practice, often the urge to over use the latest and greatest frameworks, techniques and paradigms, often only leads to a painful maintenance in years to come – and as you’ve complicated things beyond comprehension you’ll probably be the trapped in the maintenance for the lifetime of the developed code.

Keep It Simple

As new development challenges often are much more fun, than maintaining legacy code, there are a few basic things you can do to keep yourself from being the eventual eternal maintenance developer and they are straightforward:
Keep it simple
When solving a problem, make as simple and as little code as needed. Don’t wrap everything in object hierarchies, split configuration, views, models and controllers in individual files – do it only, when it provide clear and apparent value.

Names matter

Choose short, but descriptive names for variables, functions, classes and objects in your code. An object containing content for an invoice should be named $invoice, not just $x, $y or $z. Using naming of artifacts in the code provide clues to content and functionality makes it much easier for anyone – including your future self – to comprehend and understand the code when doing maintenance.

Don’t fear comments

Comments does not slow down your code. Al code is compiled at the latest at run-time and a few well placed comments may often be very valuable for the eventual maintainer. Don’t comment obvious code constructs (“don’t state the obvious”) , but do reference business rules or why something tricky is going on.

Be consistent

Find a consistent way to solve the same task/pattern every time, as it will help you focus on what the code is doing instead of the syntax expressed. If you during development find a better way to do something, remember to go back and fix the instances where applicable.

Move on…

Every developer will eventually be stuck with some development, but making your code accessible and easy to understand – the odds of you being stuck forever on maintenance duty is much lower. Great code move on from the parent and have a life on it’s own in the care of other developers if you’ve done your job right.

Function names as signaling

In most web applications there’s a host of functions (or methods if speaking in the object-oriented world). It’s widely recognized, that it’s probably a good idea to name them something, which may suggest the purpose or functionality of what the function is doing, but often developers seem to fail at making a stringent naming convention. Before starting on your next big development adventure, here are a three suggested rules for naming functions.

1. It’s more important to have a suggestive name, than a short one.

Never call a function something short but meaningless. Instead use CamelCase and make a sentence suggesting what the function does.

  • Bad examples found in live code: “process”, “fixit”, “cleanup”.
  • Good examples: “saveToDatabase”, “convertIpnumberToDomainName”, “calculateTotalPricing”.

2. Use prefixes on functions

Reserve common names (more if you like) for specific type of functions. Here are a few suggested rules:

  • “get”-functions should always retrieve and return data – never print data.
  • “print”-functions shoudl always print data to “standard out”.
  • “set”-functions should ways set data to an object (and choose if “set” also saves data or not).
  • “save”-functions (if set-functions doesn’t save properties) saves all current properties to the persistent storage (usually database).

3. Reuse data model objects in function names

If you’re data model (or object model) already contains names of entities, reuse these in function names. If a table is named “Travel”, call the function “saveTravelRecord”, Not just “saveDataRecord”.
Make consistent use of the same names, field names, properties and other entities found in the application. Using the same name for the same object all across the application, may seem obvious, but somehow developers seem to find slightly different names for the same object again and again.

While the three above tips may seem simple, do check your code and see how many places they are broken. I’ve seen countless times, and getting it right from the beginning would have cost a small effort, refactoring the code years later is a much bigger effort.

Bread crumbs in version control

I’m sorry but sometimes I really don’t get why even seasoned developers doesn’t learn the art of the commit message in version control system. All too often I’ve come across check-ins where the entire commit message just reads “bugfix”, “change”, “oops” or something just as mindless.

The effort of writing a useful message compared to the potential benefit seems to be one the best ratios – but of course the pay-back is usually some time away – too bad. Once you work on the same code for years – or even better inherit code from others, you’ll quickly learn to appreciate anyone who used more than 10 seconds on composing a thoughtful message for the future.

Here are 3 rules you should always, always obey when committing to a version control system.

Always leave a reference to the issue/bug tracking system.

All professional development uses some sort of issue tracking system, to keep track of bugs, new features and other changes to the system. The issue tracking system should always be able to tell who asked for a change, why it was asked for and what considerations was made before the code change. By leaving a reference to the issue tracker, it’s often much easier to get “the big picture” if the change need to be changed years later. To make sure you get it in, just write “Bug #number#: “ as the initial part of the commit message.

Don’t write what, write why

Don’t write it’s a bug fix – most people will know it from look either at the code or in the issue tracking system (see point 1 above), rather write why it fixes the issue (“New check to check for missing parameters”, “Now handles no search result from db correct” – not just “bugfix”).

Keep it brief.

Log messages are not a place to store documentation, user guides or any other important information. You can assume it’s the future you (or another future fellow developer) who will look at the code and try to make sense of it. Think of this, when writing the message – it’s not for the project manager, it’s not for the end-users – it’s for a developer doing maintenance work on the code in the future.

Build-in time bombs

I’ve been refactoring and refactoring some old code, and it’s kind of odd what short-cuts (or even time bombs), you’ll find in code, which apparently wasn’t supposed to live on for years.
In a now retired CMS system, we had an issue every new year, when some kind of bug would reset all “schedules” for upcoming stories and content. No-one ever got around to fix it, as the system was soon to be decommissioned – but sadly the bug did survive a few years anyway.

These days, I’m was working in the system, which came to replace the broken system from before. Here’s another odd thing – It was apparently hard coded into the editor in the backend, that stories need to have a “published date” between 1996 and 2011. As there really isn’t any documentation and the original developer has left the company, it’s hard to know why it was made so. While there probably was a reason, it’s lost by now.

 <select name="year" size="1" style="width:55px;" title="Year">
   for ($i = 1996; $i < 2011; $i++) {
       printf("<option value=\"%1\$d\"%2\$s>%1\$d</option>",$i,($year == $i) ? " selected" : "");

We fixed it by making the latest “published date” go between 1996 and current year plus one.

While it was an odd thing, I’m surely glad that we from time to time do some sort of maintenance of old code – even while it seems to work perfectly. It’s far from the only bad thing we found, and while most people worry mainly about new code, sometimes you should also remember the old stuff.

Better but Broken

Working with application development – either on the web, on the desktop or any other place – is often quite interesting. When making new releases features are added, changed – or in rare cases removed.

As a developer – or “software product manager” – it must be an interesting challenge to keep up with the users and the market to capture the features and changes to a product, which will make it better from release to release.

There are probably many ways to try to keep up – by doing research and by listening to user feedback seems to be two obvious choices, but I’m sure, there are many others. Some, I’m sure is also just a gut feeling of what might be cool new features. If you’re good – and now the users, the market and the competitors, you’re making steady progress.

Yet sometimes you miss. The slow adoption rate of Microsoft Vista might be a sign of a very public miss.

It doesn’t have to be a big miss, to chase a user away.

picture-1This weekend it happened to one of my favorite iPod Touch games – Tap Defense was upgraded to version 2.0 – and while most of the updates probably are great, there’s one little detail, which probably ensured I’ll rarely play it again (unless I find a way to fix it).

I used to play Tap Defense a lot while listening to Audiobooks and Podcasts. The new version has been updated with sound effects and music – and now the podcast or audiobook goes away (pauses) when the game is launched.

I’m sure TapJoy, developers of the Tap Defense game, are proud of their new sounds, but if I need to choose between the game and my listening to podcasts, the game looses. Please bring the ability to keep listening to what every the iPod plays, back in version 2.1.

The art of the commit (in version management)

Most developers (and certainly professional shops) working with software- or webdevelopment has understood the ideas behind sourcecode version management – no matter if they choose to use cvs, subversion, git or any of the other fine systems available. How developers use these systems, can provide an easy insight into who is the dummy, the average and the great developer.

When to commit

One of the first distinguishing signs is what they commit – is the version management system used as a backup tool or as a version tracking tool. Some seem to think, you should end the day by committing all your sourcecode (no matter which state it’s in). This is really bad sign. Others commit whenever a new file is finished and thought ready to use – which is slightly better. Others again commit once – just before a new release – and has the commit contain each and every change since last release.

In my world a commit should contain a complete new feature across all the files changed to make the new feature. The commit should preferably only address one change (a new functionality or a changed feature).

The commit message

Another way to spot bad habits is in the commit message. Is there a commit message at all? – if not, it’s a bad sign. Almost as bad are meaningless comments, which may come in all sort of varieties – “work in progress”, “bugfix”, “update”, “foobar”. I’m sure they make sense to the developer at the time of committing them, but hardly 6 months later, when browsing the logs and wondering why a certain change was made.

A less common bad commit habit is the “book style” – where the comment either contain a delta of the changed lines (literally or as a description) or the length of the comment is a small story explaining the reason for the change, why it was made the way it was and on and on.

I’d any day prefer seeing a reference to a bug/ feature tracking system (bugzilla, trac or anything like it), and a brief summary of the change in a 140 characters a less.

Tips for developing WebApplications

So it been awhile since I sort of promised some tips on developing web applications fast. This post contains my five generic tips, which may apply to you (but then again – your mileage may vary). I’ve tried to abstract the advice and not stick to PHP development here, though it’s by far the world I know best.

1. Spend time on the data model

Too often a data model is driven by code, not careful thinking, and this often causes problems has the web application develops and expand over time. When developing a site, which needs data stored in a database (as most web applications tend to do), do try to spend some time on the data model – which tables do you need, what fields should the tables have, are the naming logical and consistent, what constraints and limitations does the data model offer.

It’s often far easier to refactor code and functionality than it is changing the database tables and fields, and it can be a tremendous help while maintaining an application if you clearly understands the data its working with.

2. Get the basics working first and fast

It often takes a while to get a complete web application finished. Help motivating yourself by getting the core working first and then add features and frosting once it’s working. By having a working skeleton, I usually find it much easier guess how much work needs to finish the various features than I do guessing the work needed to complete a section (ie. admin interface) on the application.

3. Think performance and security from the beginning

Remember to think of performance and security from the very beginning. Sometimes performance – or security – may cause you to layout the data model in a certain way or structure the application a certain way. While you may be able to add performance and security during refactoring, it’s often much harder than it is keeping both in mind from the very beginning.

4. Don’t fix the future; focus on the current needs

I don’t care about the next version. I really don’t want an infrastructure in place, which can help me build the future versions of the application. I want the features and infrastructure in place for the current version I’m working on – and frankly the features in the next version has a tendency to change before I’m ready to develop them.
Too often future-proofing an application clutters the code and too often the clutter doesn’t ever come to any good use – it’s just noise once we get to the real future features of the application.

5. Naming matters

Do think of what names you use on functions, classes, variables and database tables through out the application – and choose something meaningful. A variable named $x doesn’t hint what it’s used for. Help yourself (and other looking at the code) by hinting the uses of various things by choosing meaningful names.

Mysql metadata

If you’re a developer and use mysql, I’m sure you’re aware that it’s a database and it quite good at storing data, but one of the neat things about Mysql (and most other databases) is also their ability to provide meta-data on the contents of the database.

Most people know how to use the meta-data queries in the commandline, but if you want you can also use them in your (php/perl/some-other- ) language. Here is a quick guide to some of them.

show databases

The show databases provide a list of all databases available in the datbase-server you’re accessing. It doesn’t tell you which of the databases, you’re allowed to access.

Once a database is selected, you can see a list of tables with the command:

show tables

And with either the ”desc tablename” or with the command

Show columns from tablename

(replace ”tablename” with an actual tablename from the database).

You can exclore which columns and column definition is available.

It’s probably rarely you need to use these functions unless you’re writing a phpmysqladmin replacement – often a script makes assumptions on which tables and columns exist.

If you’re developing an upgrade to an existing application/webbsite/script and the update requires database changes, you can use these functions to check if the database layout version is the one matching you application version needs. By doing this, you can provide much better feedback to the user on what’s wrong with the script, instead of just breaking horribly with database errors.