Designing Systems, the Art and Pitfalls

This article mainly based from this stackoverflow question about designing system. As I have written before about learning by teaching, this is a good example that I see. Even though I had experience designing a system, but I still cannot define exact steps needed to design it. Now I have learned much and able to provide the explicit steps of designing a system, at least from my experience.

The High Level and Low Level Module

In the context of system (application) design, a high level module is an overview picture about how the system interacts with the user, and other integrated system. Since low level module is a detailed picture about how the system interacts between each other subsystems inside. That's it, a system design are divided between two modules.

High Level Module

We need to divide the design to separated modules, because it is hard to design a system without high level (overview of the system) module. High level module are more understandable by the business users. Moreover, there are many pitfalls beside system errors, such as wrong use case scenario and wrong business rule validations. Defining those pitfalls in high level module design is easier and faster. Who does not loves simplicity, faster, and easier job? That's why we should do high level module design.

Taken from my stackoverflow answer, about a standard point-of-sales system that has the following sub-modules:

• ordering
• commiting order
• down payment
• goods delivery
• return

Here is the steps of defining high level module design:

1. Define the standard use case between user and systems
2. Pour the use cases to some collaborated diagram such as rich picture (or anything familiar)
3. Define the exceptions use cases. If the exceptions can be defined easily, put it immediately to model. If not, mark the model with the case exceptions to be further discussed with business teams. Some use case exceptions can be changing committed order, changing committed order after down payment, cancelling payed order, goods out of stock, etc.
4. Iterate the process. Usually step 3 can become step 1 (the exception can / will be another use case). For example the changing committed order can be a use case, since the change of occurring is high.
5. When the 3rd is completed without additional use case exceptions (all use case has been handled), usually I add value-additional operations.
   Those operations can be notification (email / on-screen), historical data maintenance, reminder, error-handling, etc. Some operations can be another use case as well, so maybe you will need to iterate over to no.1.
   Some example maybe when you get error during down payment settlement, maybe you will need another use case to input the down payment data manually. Or maybe you will need to maintain reminder system in another system.
6. Move to low level model

Well, each point can be separated as another discussion.

Low Level Module

Low level module design, on the other hand gives more detailed view in the systems and it shows how each of the subsystems work between each other. Many times, low level modules are overlooked by the management because it is far very faster to immediately begin to code than creating the low level module. Then what is the benefit of low level module design?

These are the benefits of low level module design that is often overlooked:

1. It can act as a documentation
   Class diagram, database design, state diagram, flowchart, sequence. Everything can be taken as a technical documentation or "blueprint" of the system. Is it needed? Yes in most cases, usually in first step of debugging
2. It catches pitfalls, errors and exceptions early
   Most of the time error and exceptions are being caught during integration testing. When during testing and find some of the error, you will review the general process of the system. At that time, it is too late because your code already been constructed with your database structures
3. It design your code base clean
   Little hacks and tweaks are sometimes (most of the times) done to fix something during the testing time (see point 2). Having a low level module, you are forced to define some general structure of your code base, and pitfalls can be avoided early, making your code cleaner and less need to refactor
4. It can be reviewed easily
   Discussing designs with peers using low level module design will be easier and faster, compared to reviewing code
5. It can be used as basis of review and evaluation
   After the code has been completed, you can review the mechanism and structure with low level module design. This will help to find pitfalls or unfinished works earlier (before integrated tests)

Well, there are many benefits but often overlooked by management, because usually they only make schedules with waterfall model. That is, having the development going forward (from design, code, testing, publishing) without handling for exceptions in between (bug fix during testing, redesign during code, etc). And the benefit of low level module in a simple CRUD application seems overkill (even though nice to have) for most management, that in their consideration: "it is okay to have a buggy code published rather than having 40 hours of designing low level module.

Then how do you design low level module? Well, the answer lies in many books, such as UML guidance for OOP, etc.