Software Design approach: Design -> Build -> Test -> Refine Design Document

Question

Problem that needs to be fixed

• Design document is not in sync with actual code
• Keep Manager happy

Scenario:

• Used code from an existing application and made a new one from it.
• Current documentation is out of sync with existing code so didnt rely on it.
• No time for POC as there are deadlines to meet.

Is this the Correct Approach ?

• prepare a design based on your understanding of the code
• Build application
• Test applciation to see if everything works
• Refine the design document to reflect the changes

What other would you suggest?

Answer 1

I think that everyone who has bitten the bullet and done up-front design, with properdocumentation, will agree that it actually shortens the development timespan - it's not a "keep the manager quiet" thing.

Answer 2

You didn't specify software type, but I'm going to assume by the lack of time for design, that we aren't talking critical functionality or embedded. So on that assumption:

Find some way to combine steps 2 and 3 into a parallel step. Not necessarily saying TDD, although that works, but have at least minimal test plan for each interface. When you finish a "task", have it tested (preferably by someone besides yourself), and fix critical errors before moving on to next task.

If you save testing for last, it will take you longer, add risk, and absolutely ruin your code.

Answer 3

"Used code from an existing application and made a new one from it."

This is a bad practice. Copy-and-paste cloning is very, very expensive. It seems cheap to copy. For the entire service life of these applications, however, you have more than doubled the maintenance cost. Every bug in the original must also be (a) located in the clone and (b) thought about and (c) fixed.

Please do not do this. I consider it as a hint that people need to find a job that doesn't involve programming.

"Current documentation is out of sync with existing code so didnt rely on it."

This is a consequence of cloning. It is a good reason why cloning an application is a bad practice. It leads to documentation that doesn't match EITHER the original app or the cloned app.

"No time for POC as there are deadlines to meet."

Someone mislead the project manager about how much time the project would take. It's your job to provide realistic, fact-based information.

"prepare a design based on your understanding of the code"

Only if you're going to build one application that does both things.

"Build application"

Only if it is not a copy-and-paste clone of another application.

"Test applciation to see if everything works"

A little late for that. You should have had some test cases must earlier in the process. First is ideal, but during the development is almost as good. After the fact is -- well -- hard to manage and creates rework.

"Refine the design document to reflect the changes"

This is way too late in the process to be of any value. Design comes first, actually. Then test plans and procedures (e.g., unit test programs). Finally, code shows up that conforms to the design and passes the unit tests.

Answer 4

An interesting reading : Code As Documentation

I am facing similar problems, the design doc could never keep up with the changes in the code. Hence my 2 cent solution is to:

1. Write a high level design doc initally to guide your programming
2. refine your code and make it as simple as possible via continous refactoring, DRY, TDD
3. Update the design doc with assumations, optimisation of why you did it
4. keep the design doc at a bird eye view level, while the code explains the micro details.