Posts Tagged ‘Best Practice’

Build Your Software on Firm Foundations…

Monday, March 23rd, 2009

What makes for a successful software development project? I was mulling over a number of projects I had been involved with in the past, some very successful, some not so, and thinking about the key differences between the two. There are any number of aspects that can be considered – the quality of project management, clearness of requirements, thoroughness of the analysis, quality of execution and technical leadership to name but a few. Here I am going to focus on two key technical aspects, not being a career project manager, and explain why they are both important and also both frequently neglected.


From my experience there are two main aspects to a technically successful software development project, the Software Architecture, and the Software Engineering Process (I am taking it as read that your teams have the basic capabilities to develop software using your chosen technical platform, which in my case is Java).

(more…)

Tags: ,
Posted in Software Architecture | Comments Off

Top 25 Most Dangerous Programming Errors

Thursday, January 15th, 2009
The SANS Institute has published a list of the top 25 most dangerous programming errors and reading through the list was pretty much like meeting a bunch of old friends. Such lists may seem self evident to some but that doesn’t stop development teams falling into the same traps today that were being fallen into ten, twenty or even thirty years ago.
The first thing that struck me was that the list talks specifically about internet application development. Now some younger commentators have pointed out that ‘all this was covered in my degree’. However for anybody who’s been in work for ten years or more, such courses would not have covered preservation of web page structure or cross-site scripting issues because the internet was so young that it was not an issue. It also got me thinking about the wider issues around coding standards and reviews, and why we are so bad at creating and adhering to standards, performing reviews. In short, development teams are still woefully ineffective at learning from the mistakes of others.

The SANS Institute has published a list of the top 25 most dangerous programming errors and reading through the list was pretty much like meeting a bunch of old friends. (more…)

Tags: ,
Posted in Engineering Process | Comments Off

Method Contracts! Method Contracts! Method Contracts!

Monday, July 14th, 2008

I recently spent a few days back-filling test code to help a team meet one of its its quality objectives – namely unit test coverage – and the scany level of documentation within the code re-enforced my views on properly documenting the contract of a method. The methods I wrote tests for had the minimum of JavaDoc, enough to ensure no warnings from Eclipse, but nothing beyond that. So I had an idea of what the method was supposed to do, and roughly what the arguments were for – but no indication if null was a valid value for a given argument, or what would happen if an argument value was non-null but invalid.

To write tests for the method contract I had to pick through the underlying code – far from ideal, as I’m now inferring the contract from the code, and the code may not be correct. And this particular organisation hadn’t adopted the de facto approach to validating method arguments as documented in the excellent Effective Java (recently re-issued for Java 5) by Josh Bloch.

Briefly, the method contract consists of two component parts: the explicit contract – the method name, arguments and their types, and the implicit contract – which arguments can be null, the valid range of values for a numeric argument, etc. The degree of documentation for a method and its contract should be proportional to its complexity and the level of exposure the method is likely to receive – and it doesn’t get much more exposed than a component interface, so these should be very well documented indeed. The objective is to leave no ‘wriggle room’ in the specification – either for those developing an implementation or those who might want to use it. Or indeed, test it.

By providing thorough documentation for a method you are in effect crystalising the purpose of that method. As a developer it clarifies what you are trying to achieve; for a user of the method it helps them to understand what the method does and how to use it correctly. It should also tell them what error conditions exist and therefore allow them to be catered for.

This may seem overkill for a one or two man project, and you may be justified in short-circuiting the process to an extent. However it is vital in larger projects, and putting the documentation with the method ensures that future maintainers and users of the code do not have to hunt around for supplementary documentation. Or the original author, to explain what is going on. And even for a one man project, coming back to code cold after, say, 18 months, you might just find that the documentation refreshes your memory…

Briefly, the method contract consists of two component parts: the explicit contract – the method name, arguments and their types, and the implicit contract – which arguments can be null, the valid range of values for a numeric argument, etc. The degree of documentation for a method and its contract should be proportional to its complexity and the level of exposure the method is likely to receive – and it doesn’t get much more exposed than a component interface, so these should be very well documented indeed. The objective is to leave no ‘wriggle room’ in the specification – either for those developing an implementation or those who might want to use it. Or indeed, test it.
By providing thorough documentation for a method you are in effect crystalising the purpose of that method. As a developer it clarifies what you are trying to achieve; for a user of the method it helps them to understand what the method does and how to use it correctly. It should also tell them what error conditions exist and therefore allow them to be catered for.

Tags: ,
Posted in Development, Engineering Process | Comments Off

Testing, testing

Wednesday, February 13th, 2008

There’s a lot to be said for test driven development. Next to documenting the code, testing is the other bane of a developer’s life that prevents them from moving on and doing other, ‘more interesting’ work. All the better then that the approach to writing code should include the writing of test cases. Write some code, write a test case, make sure it passes, then OK, move on to the next bit. You build confidence in the existing code as you add to it.

Done this way testing doesn’t need to be all that boring. And one of the keys to this is the structure of the code you test. Listen carefully when you ask why testing is a bind and what you’ll find is that developers don’t necessarily mind writing test code, its the work in setting up the right data for the test cases that takes the time. And then updating it as the system evolves. What is happening here is that the unit test exercises an entire monolith of code which in turn requires more detailed configuration than just the one class being tested. And because so much code is being exercised, a change in any area can result in tests in other areas failing. And so the myth that testing is time consuming is perpetuated, because the unit test isn’t a proper unit test.

Producing testable code doesn’t take much additional foresight and in a way is connected to one of the key tenets of OO design – correct assignment of responsibilities. If classes are small and tightly focussed then they are easier to test. Likewise methods – are your methods properly decomposed and does each method have a single clearly defined purpose? If the answer is ‘no’ then you are building code that is harder to test. Moving up a level, you should be designing components with clear and clean interfaces, and using standard techniques such as the Business Delegate pattern to minimise coupling between them. Which, in turn makes it a relatively simple matter to implement component stubs to support the isolated testing of classes, which in turn wipes out much of that data set-up issue.

In short, difficulties in testing OO code can often be ascribed to the structure of the code. Here is a list of points to consider:

  • Write many small, focussed classes rather than fewer, big classes.
  • Restrict methods to performing a single purpose – decompose ruthlessly.
  • Refactor shared/duplicate code into super-classes or helper classes as appropriate.
  • Don’t expose private methods unnecessarily just to make testing easier – use something like the PrivateAccessor class from the JUnit Addons project.
  • Create interfaces for components to allow simple stubbing.
  • Avoid static methods wherever possible.
  • Use the Business Delegate class to minimise coupling between components.
  • Use JUnit to build tests, and Emma to check your coverage

And as I’ve touched on Emma, an excellent tool which allows you to see, line by line, which code has been tested and which has not, I shall finish by briefly discussing test coverage. How much of your code should you test?

Your quality department would probably say “100%” but unless you’re working in a high-risk area (for example, fly-by-wire flight systems for airliners) then you probably won’t have the resources to do this. My take on unit testing is as follows:

  • Don’t write unit tests for bean getters and setters (I’m assuming here that your getters and setters do only that, and contain no complex processing), but do make sure they are exercised.
  • Don’t write test cases to demonstrate that assertions are thrown correctly (you are using assert, aren’t you?).
  • Maximise test coverage on your framework code (errors here will affect your system across the board)
  • Prioritise test coverage on your functional code. Focus on the more complex, riskier and shared code first.
  • If you are back-filling tests on code that has already shipped, focus on those areas causing the most disruption to your customer or support team.

If you’ve written small classes with tightly focussed code, it is actually quite difficult to get your coverage beyond 90% anyway, and the cost of completing those few extra percentage points will, for most situations, far outweigh the benefits.

Next time, the importance of the method contract.

Tags: , ,
Posted in Development, Engineering Process | 1 Comment »