SWE.3 – System Architectural Design

Timing of documentation

Describe the detailed design  b e f o r e  your implement the code. Often, the detailed design is described after the fact, meaning after the code has been written.

Why is that a problem? The unit test should check whether the code fulfils the detailed design. If you write the detailed design after documenting your code, the point of the unit test is lost.

Now, you could argue that you may not need the unit test. The point is that you should derive your detailed design form your architecture and not from the code. If the chain is broken, then suddenly the content of documentation and all the tests do not make sense anymore. So, the detailed design must be written before you start writing your code.

There is nothing wrong to iteratively develop detailed design and code step by step.