Main Content

Specification, Design, Implementation, Testing and Documentation - stages of a (Java) programming project

Archive - Originally posted on "The Horse's Mouth" - 2011-07-21 08:58:56 - Graham Ellis

There are two key factors in writing even a simple program - working out what you want to do / how you're going to do it, and then actually doing it in the language of your choice. Call the two phases "design" and "implementation" if you like.

The design phase can be very much more 'free format' - artistic, and the implemetation is more prescriptive - scientific. And as a result, different grous / types of people will find one phase, or the other, the more challenging. There are those who can see the design easily but have trouble reducing it to the very specific and accurate code statementas, and there are those who struggle with the design, but can then easily convert it into code when they have the design figured.

It's a good idea to split the phases - design and inplementtion - somehow. And it's worth adding a third phase - specification ("describing the problem") onto the beginning. Many is the system that's been written where the specification hasn't clearly been defined, which has resulted in a very nice final program ... which won't actually do what it was intended for!

It's a good idea to split the phases - design and inplementtion - somehow. And it's worth adding a third phase - specification ("describing the problem") onto the beginning. Many is the system that's been written where the specification hasn't clearly been defined, which has resulted in a very nice final program ... which won't actually do what it was intended for!

Let's take an example showing each of the phases - from my Java course earlier this week. (The fact that the target language is Java doesn't effect the first steps - but becomes vital in the final coding step).

Specification

Working out what you really want.

"How long a train do I need to take "xxxx" passengers to Weymouth?"

is translated into

"Given an expected number of passengers, work out the minimum number of carriages on a train such that 4 seats in 5 will be occupied. Railway carriages on this line can take up to 75 seated passengers and note that there's a limit of 5 carriages per train on the service you're working out"

Design

Start off by setting (as constants) values that don't change. The ask the user to enter the number of travellers.

Write a loop to start off with one carriage, and see what the loading factor is. Keep adding further carriages in a loop until (a) the loading factor is less that 80% or (b) the train is 5 carriages long.

Print out the train length required, and what the laoding factor will be. It might be a good idea to revisit the specification at this point and decide whether or not to add a further output if the train is 5 cars long to say whether the loading factor is within specification, if the train will be very full indeed, or if people will actully have to stand.

Implementation

This is the bit where you translate into code. I would suggest setting up the framework of the program first (the public class and method main in Java), and then writing the design into the code in the form of comment statements. You can then fill in the code.

Testing

Beyond the writing process, do not forget testing (and you may jump back to earlier stages as you test). Try the code initially with easy, know user inputs that you can work out for yourself. Try a couple of more complex ones. Think of all the special cases that may occur and try each of them. Try things that you know are wrong, and make sure that you program handles them in an appropriate way.

Documentation

Remember that you'll need instructions for the user, a description of how the program works for the maintainaince programmer, and appropriate formatting and labelling of the results that the program produces so that the user knows how to read the results (and so does the person who's sent a copy of the results by email!)

There's a completed coded example showing the program I've talked about - up to the coding phase - [here].

Example from our Learning to Program in Java course.