As developers, we are often rewarded with praise (or more) for turning new features around quickly.  If your company estimates that a particular feature will take eight hours to write, and you take only four, the company’s making a tidy profit, you can move to the next item in your schedule more quickly and everyone is happy.  This is all very well, so long as that feature has been written properly and in accordance with your company’s general approach; everything ranging from naming conventions right through to the organisation of the filesystem.  If it hasn’t been written properly, then you have incurred technical debt, and at a point in the future either you or another developer maintaining your code may need to spend more time writing a feature or changing your feature than anticipated.

This can cause all manner of problems.  When you come to develop on from your last feature, you might estimate that another bit of functionality will take 8 hours to write.  However, when trying to hook in to the existing feature, you discover your technical debt, and end up having to refactor the existing code to allow you to do what you wish.  This might take another 4 hours.  This might not seem to be a disaster; after all, you were 4 hours up on the first feature, and we’re just back where we should be now, right? Wrong! It is important to remember that managing our time isn’t  just about managing the absolute amount of time taken, but keeping to schedules.  The 4 hours it takes to sort out the mess in this second round of development delays the next item in your project schedule, which might result in a disappointed client.

In my opinion it would have been better to take the full scheduled 8 hours in the first round of development and avoid the unexpected hold-up during the second round of development.  The 4 hours in the first instance are less expensive than the 4 hours in the second, as they’ve less of an effect on surrounding projects & priorities.

The trouble is, at the time the new feature is written, it can be difficult for someone non-technical to tell the difference between it having been done quickly and it having been done properly.  In fact, from an end-user’s point of view, the system can look absolutely identical.   So, given two developers, one who can turn the feature around in 4 hours, and another who takes twice as long at 8 hours, which will the project manager or client be more happy with? My money would nearly always be on the 4 hour guy. But long term, the 8 hour guy is actually going to be less expensive to run, or will at least facilitate more accurate estimates and quotes on the same system in the future.  The problem is, as developers, we need to resist the temptation to be the 4 hour guy. The short term praise can be addictive and it’s understandable why it seems easier and more tempting to do things as quickly as possible and worry about the consequences later.

What I’m noticing is, in 2008 I WAS the 4 hour guy. I was turning around features faster than other people had in the past, and grew a reputation for being quicker.  While I was quicker at the time, now, 4 years on, when I’m revisiting those sites and starting to improve or extend them, I’m paying off my technical debt with ‘expensive’ rewriting and refactoring.  So now I’m in the position where I am expecting the implementation of a change request to take a given amount of time, but on loading up the project and seeing the way it was written in the first place, the implementation is taking much longer.  This extra development time is difficult to explain and to justify to those responsible for project scheduling, and is something that I’m going to really strive to avoid in the future, even if it does seem to take me slightly longer to develop new features than before.

It seems sensible to finish this post with one of the more famous quotes about computer programming. I’m sure you’ll have read it before…

Always code as if the person who ends up maintaining your code is a violent psychopath who knows where you live

Trust me, it’s bad enough even if it’s YOU that ends up maintaining your code!

In ‘the olden days’ when processes such as updating your Facebook status or posting a tweet were done through bog standard HTML forms posted by the browser to a new page request, it didn’t matter when the page I was posting to didn’t get posted to fully, or didn’t respond, because I could hit refresh (or press the submit button again or whatever) and the request would be resubmitted.

Some web developers (myself, at times, included) HATE impatient users who will press buttons twice or refresh the page because it’s taking too long. In a lot of apps this means that the action is applied however many times the button is pushed (e.g., two or three orders are placed instead of one). But the reality is, sometimes there is a genuine need to refresh or resubmit, because nothing is *ever* going to happen with the first request that was sent. This could be due to an internet connection problem or a server-side problem.

Now, more and more web sites seem to favour the “no new pageload is necessary” approach which, in itself, I do not have a problem with – at all. What I do have a problem is is when the developers choose to disable the submit button once I press it – permanently. Because if nothing happens for 2 or 3 seconds, I am pretty damn sure that that status update or tweet is never going to get posted. What I would like to do at this stage is to resubmit the request. But at this time, there is no easy way to do this:

• I have not requested the page in a traditional sense in the browser, so I can not push the ‘refresh’ button; that would reload the whole page and typically delete the tweet or status update that I have written.
• The submit button for the form is permanently disabled, so I can’t press it again to submit again.

Even if the JS implementation gracefully degrades (e.g. if I have no JS support I get the “old fashioned” style normal form), this situation occurs for people with JS enabled. Just because a user has JS enabled doesn’t mean that their web connection is faultless or that they won’t need to push that submit button twice!

I was trying to think of a way around this issue that doesn’t require scrapping the AJAX submission all together, and came up with only one potential solution, which is to disable the submit button but only for an elected period of time (say 2 or 3 seconds), so that if the request doesn’t get responded to in that time, the user is given an opportunity to re-submit.

Anyone else’s ideas of how to work around this problem would be gratefully received through the comments section; I don’t want to write software that frustrates people in the same way that this frustrates me!

The main reason for Javascript being used to progressively enhance the user experience rather than be a fundamental ‘requirement’ is cited as making the site accessible to as many people as possible. Importantly, many mobile devices don’t fully support Javascript (Smart Phones tend to, but I’m talking true mobile phones here) and screen readers certainly don’t support Javascript. Realistically, the percentage of visitors falling in to the ‘browsing on a mobile device’ or ‘using a screen reader’ will be low, and often low enough for a client (or yourself) to make the judgement “we’re not going to bother”. It is important to consider that there are advantages to graceful degradation other than making the site as accessible as possible:

Google, Bing, and A.N.Other search engines – search engine spiders are still fairly basic creatures. If your site navigation doesn’t load a new page but instead loads new content in using Ajax when you click the ‘About’ link, how are search engines going to find and index your ‘About’ page content if the site is not navigable without Javascript? It’s quite simple to make things like this degrade; if Javascript is disabled the link should go to index.php?page=about rather than nowhere. Importantly, many clients think that google is the most important visitor; if they’ve forced you to put lots of keywords at the bottom of the site despite your pleas for them not to then they wouldn’t be very pleased to find out that the search engines can’t get any further than your home page.

Application Design – Designing the application so that it works without Javascript and then adding Javascript afterwards often makes the system architecture much more understandable and ‘rigid’. In fact, if done correctly, this can speed up the Javascript implementation process. Looking back to our previous example, index.php?page=about will load a completely new version of the page with header, footer and all the bells and whistles. How about, if you click the ‘About’ link with javascript enabled, it will load index.php?page=about but through AJAX? Using HTTP_X_REQUESTED_WITH we can detect that it was requested through AJAX and serve just the ‘meaty’ bit of the page; ie the content that is changing, rather than the whole page. Does this really add much time to the development process? In my opinion, no it doesn’t!

Of course, the user experience will not be identical without javascript, but in my view it is still important to support users with no support for the language on their device, or even those that choose to browse without it. It is my view that you can treat support for when Javascript disabled in the same way as many designers treat support of Internet Explorer 6: The site should work, but it doesn’t necessarily have to be perfect. Sticking to this general guideline will not add huge amounts of time to the development time of a project, and if it does… you should take a look at how the system is designed, because it really shouldn’t.

Explaining and justifying your decisions

At the most very basic level, take this bit of code for example:

ksort($files);

To most PHP developers it is obvious that this bit of code sorts the $files array in key order. But it is not obvious to any PHP developer *why* I have done this. Adding a comment to say what I am doing and why would help speed up the recognition of what this code does; but more importantly, explain why this code is here.:


/**
* Sort the $files array in Key order. We want them displayed on the
* page in added order, and the $files array is not necessarily
* sorted in that order before this stage.
*/
ksort($files);


Using code comments as a tool: Autocompletion

There are other areas of an application where documentation can be even more useful. Modern Code Editors and IDEs will read what are called ‘docblocks‘ at the top of class, method or function definitions and add the information in the docblock in to your autocomplete prompts. So how do these docblocks work?

Docblocks are generally in this format (opened by /**, closed by */, with a * at the start of every line inbetween) and always apply to the next uncommented line of code. In this case, the line of code beginning with $page_posted_to = is documented by the docblock above.:


/**
* Determine if the page has been posted to with an action.
*/
$page_posted_to = (array_key_exists('action', $_POST) && !empty($_POST['action']));


Within docblocks you can contain ‘tags’. These ‘tags’ begin with an @ symbol and are often read or interpreted by documentation generation utilities or IDEs/Editors for autocompletion. A comprehensive list can be found on the Wikipedia page for Docblocks. Using these tags can encourage you to include information in your documentation that you might forget to include normally, ie the expected data type of function parameters.

At it’s most basic use, docblocks usually look something like this when describing a function or method:


/**
* This function adds two values together
* @param int $a The first value
* @param int $b The second value
* @return int The value of $a + $b
*/
function add_together($a, $b) {
return $a + $b;
}


As you can see, including these docblocks explains in plain english what the function does, what parameters it expects, and what it will return. This can save the next developer that reads your code tonnes of time and headaches, but most importantly of all, will make your code editor or IDE (if it supports autocompletion and docblock parsing) much more intelligent when it comes to helping you call your own methods or functions.

The idea of the ‘architect’ of this system was that any interaction with databases or storage of data; ie the models; would be shared in the central library.  This would mean that changes such as the one I worked on with is_deleted = 1 would be simple and made in one place, and one place only.  A true implementation of the ‘Don’t Repeat Yourself (DRY)’ principle.

The nature of this platform is that it is exactly that. A platform.  This typically means that no two implementations of the platform are identical, so to speak.  The platform is built upon and ‘extended’ to do what the individual customers want from their online shop.  This sometimes means that custom product ‘getter’ blocks of code are written.  Often, the ‘quick and easy’ approach had been taken with these , and they had simply been added as standalone functions in the individual project’s library, called things such as getAllProductsFlaggedAsSpecial()  This obviously meant that when I implemented my is_deleted changes in the central library, and wasn’t aware of the custom nature of these custom product selectors, the sites that used those custom product selectors continued to display deleted products.  Big oops!

This now means that I will need to go through the individual implementations of the platform, search for any custom product SQL that is being built, and add the AND p.is_deleted = 0 in to them.

This whole problem got my thinking about how I would approach this issue (The need to build custom product getter functions in individual implementations of the platform), and here’s how I think I’d do it.

I think I would ensure that all custom product getter functions were in fact methods in an extension of the main Model class that then called a buildWhereClause method that added any global product SQL (eg AND is_deleted = 0) in, like this:


class Model_Product extends Base_Model {
...
function buildWhereClause($sql) {
return 'WHERE p.is_deleted = 0 AND '.$sql;
}
...
}



class MyShopNameModel_Product extends Model_Product {
function getProductsFlaggedAsSpecial() {
...
$sql = "SELECT * FROM product ".$this->buildWhereClause('is_special = 1');
...
}
}

Essentially, what I learnt here was that the developer to begin with that wrote these ‘quick functions’ saved his or herself half an hour or so, but cost me (2-3 years later) a fair amount of time in debugging.  I think this is evidence that coding things the quick way and implementing a fast solution is often a false economy, and someone later in the life of the software will have to spend the time saved (and possibly more) to work around the disadvantages of the quick approach.

The Concept

The concept behind this is simple.  Every developer can be responsible for the code in any project.  As mentioned above, this means that bug fixes can be made by any developer, and new features can be developed by any developer.  Here’s wikipedia’s current take on the matter:

Collective code ownership means that everyone is responsible for all the code; this, in turn, means that everybody is allowed to change any part of the code.

The Advantages

In my opinion this introduces the following advantages.

• If a member of your development team is immersed in an important project and needs to be allowed to “get in the zone” and work interruption free, then if code they have written is deemed to be broken, any other member of the development team can fix the problem.
• This increases exposure of application code.  The more developers that have seen code and got their head around the way it works, the better!  When the developer that wrote the code leaves, it would be helpful to have other people who have at least seen the code and knows that it exists!
• Fresh pairs of eyes can foresee other problems with the code.  Imagine constructing a delete query using a function called constructInClause, which is passed an array.  This will return an SQL IN() clause statement.  “Hang on a minute, what if the function constructInClause returns an empty string? Won’t that delete everything from the database?” – better to spot this before rather than after the bug is exposed.

The Disadvantages

With every new approach comes disadvantages alongside the advantages.  Unfortunately, I do see a couple with this one:

• Allowing other developers to fix bugs and modify code can mean that they will not necessarily bear in mind the full knock on effects of a change.  Dependencies on code working a certain way are commonplace – even if not ideal – in web based applications.  (Note: Unit Testing could probably avoid this situation!)
• There is a danger of one person in the office becoming the “bug fix person”.  Not many developers enjoy fixing bugs all day, so in my view it would be important to try to make sure that responsibility for fixing bugs is shared equally between the development team.

Will I be encouraging the company I work for to encourage collective code ownership?

Probably, yes!  It seems like a very sensible idea, especially considering that at times interruption to fix bugs is really quite infuriating!  If the bug fixing could be assigned to the “most interruptable” developer at any one time, I’m sure that productivity and developer mood would both be improved.

1. Make sure you understand the problem in full.

Generally, when we are presented with a problem by either a client, or a project manager, the problem has been simplified somewhat.  A 15 minute phone conversation or meeting is condensed in to a three sentence paragraph asking you the best way around a problem.  In my eyes, there are a couple of approaches to avoid this.

1. Be involved in the meeting, or the phone conversation.  This is not always possible – not every developer wants to be interrupted every 30 minutes by client questions, and not every developer is necessarily comfortable talking to a client.  But listening in on (and not participating in) a conversation could always be an option!  This means that you get to hear everything that the client has said about the problem.  It’s to be expected that the person relaying the message will miss out minor (but not necessarily insignificant) details.  After all, repeating every phone conversation in full could get a bit tiresome, you’d imagine!
2. Know to ask the right questions. A client asks to make their delivery fee increase with every product added.  Let’s say, increase the delivery fee by 30% for every additional product that needs delivering.  This is simple enough, until you consider that the delivery fee could easily escalate way out of control.  A £10 standard delivery fee could soon escalate to around £50 if someone bought a large amount of products.  This could discourage a purchase.  So should a limit be introduced for the maximum delivery fee?  Remember, the client probably hasn’t thought around this issue.  Asking the question and getting an answer before work starts could save you from having to rewrite a chunk of code.

2. If dealing with unfamiliar technology… allow some research time!

If you’ve been asked to implement an unfamiliar technology, take 10 or 15 minutes to research how it all works.  15 minutes spent now could stop you from estimating that something will take 5 hours when it might take 20, or from estimating 20 hours when it might take 5!   Additionally, when estimating how long the work will take, remember that you will probably spend a fair chunk of time reading documentation and not actually writing code.  In many places this would be considered billable time – and it should certainly be taken in to account when working out how soon you could deliver the work.

3.  Remember to allow time for testing and bug fixing.

Not everyone does this, but in my opinion it is essential.  Allow some time for proper testing and the time it’ll take to fix bugs (this can only be estimated) as well as the time taken to write the code in the first place.

4. If dealing with third party services, you can’t accurately promise a deadline.

A lot of the work I do involves integration with third party services – payment gateway services, SMS services, etc.  These all involve an account application and signup process, and sometimes this process depends on the client completing a form, or submitting payment for the service.   I have found that it is almost impossible to accurately estimate a “go live” date when an aspect of your application depends on a third party service being ready for use.  If you do provide an estimated go live date, it could be worth putting in a note that it depends on the client’s service X application being complete by date Y.

5. If you feel out of your depth, don’t be afraid to say!

This is a very important point.  If you are not confident about working with and fully understanding the technology that you will be using, tell your manager or your client! It’s better to say at this stage than to blindly assume that you will be able to work something out during the work.  They will be a darn sight happier this way around than if you go out of your depth and then the project is late or massively over budget.  Saying now typically will have one of three results:

1. Your company will turn the work away to avoid a problem (or, your client will go elsewhere).
2. Measures will be put in place to avoid the issue. Billing by the hour, or using another developer, for instance.
3. The project will be quoted anyway at an estimated rate, and your company will take a risk. In this case, you at least said something at the start – the risk taken was by someone above you.

These are only very basic steps that can be taken to avoid a problem.  But one thing is for certain.  It is typically better to under promise and over deliver rather than the other way around.  You just have to be careful that you don’t fall in to the habit of *massively* over-quoting projects, because this can have a detrimental effect in terms of reducing the percentage of accepted quotations.

My reasons for this decision are as follows:

1. Database collation.  Searching for strings LIKE '%Ed, Ed & Eddie%' starts to get complicated if you have converted & to & – you have to remember to convert entities in your search string as well.  This could also potentially mess up the effect ORDER BY clauses in the SQL queries you write have on the dataset.
2. Data Integrity.  If in the future I decide that I all HTML, or just specific previously blacklisted HTML tags to be allowed, the data is all still complete and certain aspects of the data have not been removed.
3. Application Consistency.  I know that if I am ever displaying data selected from the database it will need to be ‘sanitised’ before being displayed to the user either in repopulated ‘edit’ forms or in a normal ‘view’ type screen.

I also did a little bit of research in the cakephp manual (as we will be using cakephp for this next project) to see what cakephp creators thought about this and it seems they reached the same conclusion (quoted from this page):

For sanitization against XSS its generally better to save raw HTML in database without modification and sanitize at the time of output/display.

They don’t give any specific reasons but I imagine that their thought process was similar to mine.

Starting with the basics, organisation in projects can be as simple as ensuring that you store all information supplied by the client with the project, in a folder called something like ‘assets’.   Typically I would split them by asset type – images for web, images for print, documents for web download, internal documents, other – and perhaps include a ‘supply date’ in the filename of each.

Next, write stuff down!  If a particular part of the project depends on an external service being available, write this down in a document that stays with the project wherever it goes.  Any useful information that is in your head the day you write the code for the project should probably be written down.  You more than likely won’t remember in 2 years time when something goes wrong!  All of this information could simply be stored in a README file.

Good organisation doesn’t boil down to simply putting things in to folders, or keeping notes.  Of course, these actions are a part of the organisation, but don’t cover everything.  More importantly – especially in the IT industry – consistency can be the best time saving characteristic you can introduce to your work.  Being consistent is almost synonymous with being organised when it comes to your project management…

I save time (and frustration!) by:

• Naming projects consistently.  My project name tends to match the main part of the domain name on which the web site or project will be hosted.  If I’ve a domain called edwardyarnold.co.uk, the project in my subversion repository will be called edwardyarnold.  This makes it a lot quicker to put my hand on the correct project if a change needs to be made.
• Naming the associated MySQL databases consistently.  For the above project, the CMS database would be called edwardyarnold_cms.  If the site were an ecommerce site, it would be called edwardyarnold_ecom.  This makes finding the relevant database in a phpmyadmin screen much quicker than if the databases weren’t named consistently.
• Ensuring that if a project is replaced with an entirely new version, it is archived with a date.  If I replaced the edwardyarnold.co.uk site with a completely new build, I’d move the current project to edwardyarnold_2010_archive and create a new one to replace the old.  This is a better approach to dating the new version of the site – the new version of the site would still exist in 2011 but would appear to be out of date if dated 2010.  Annoying to anyone who didn’t know that that was the ‘latest’ version of the site.
• Naming administration area directories according to a set naming pattern (I won’t disclose that here).  This means that anyone who I work with that knows the pattern can find the administration area without looking up the directory name.  (They will of course have to look up the username and password, if not saved in their browser).

These save a tiny amount of time individually, but collectively – and applied over multiple projects – the tiny amounts of time soon add up, and you can start to actually notice the saving.  Additionally, following these ‘rules’ means that new people joining your team can begin to understand and get a grip of the way you work quicker than if everything was done differently for each project.  In larger organisations this can reduce recruitment costs (remember, downtime whilst training your new staff member is a hidden recruitment cost…!) as well as saving your existing team time.

Until I worked for a couple of established Web Development companies, I never realised the importance of a ‘Checklist’ at the end of a project.  You know, simple things.  Does the site’s markup validate?  Do all images have alt tags?  Is php display_errors off?  But even after getting in the habit of ticking all of the items off this checklist for every site I build, there are still little mistakes that creep through – miscapitalised letters, incorrectly pluralised nouns… eg “There are 1 comments on this post” should be “There is 1 comment on this post”.   No checklist can possibly cover all of these possible errors (though the one I link to later in this post gives it a good go!).

The best way of discovering these problems is to ask a favour of (or even to employ) someone you know – preferably without a technical background – to go through the site and see if they can spot anything that needs changing or fixing.  You will find that they will probably produce a list twice as long as your original checklist!

The beauty of this approach is – as well as spotting spelling mistakes and other simple errors – you may also get some vital usability feedback, especially if you are with them when they are checking the site.  Do they seem frustrated? Did they use the site in the manner you would expect them to?

I was once fortunate enough to be behind a one-way mirror in a usability testing session and it was simply amazing.  We had a captcha image on a form (I know, I know.. don’t start) and the error message was misunderstood or found to be confusing by nearly every user.  The abandonment (and frustration) rate on the contact form was therefore extremely high.  This kind of problem would not normally be picked up in smaller projects where a usability testing session is not included (and you wrote the error message – so find it simple, right?), but if you run through the site with someone to whom the site is fresh, there’s a much higher chance that you will pick up the problem.  Remember that this issue wouldn’t be picked up by a checklist either!

So.. checking through a site with somebody non-technical (and who has never seen the site before) can save you a whole bunch of headaches in the future.  And remember – if you’re launching your web sites without a flight check list (check this one out from Box UK), that’s probably one of the first things you should consider implementing in your project schedule.  It will save you a lot more support time than it costs you.