Understanding a Software System

The need to understand a software system comes up many times during the career of a software professional. A common situation is that you have just been assigned to a new software project. You'll be working on a system that is unknown to you. Your first task is to fix a defect. Where do you start?

Undoubtedly, you first have to understand the system, or at least understand a portion of the system that you have to modify. Without understanding the system your changes will result in new defects. Here is how to get started:

1. Identify which use case is affected by the defect. The defect report should give you a lot of clues about this. If a written use case doesn't exist, then write it. Expand out those areas of the use case where the defect is. Ask folks who worked on the system to review the use case that you wrote. At least ask some of your peers to review it.
2. Draw a block diagram of the system. Start with the externally identifiable structure. Are there any libraries, packages, modules of code that stand alone? Draw a rectangle for each module. Draw a line between them for each dependency that you find. Have a peer review this for you as well.
3. Draw a sequence diagram for key interactions from the use case. Of special interest are initialization sequences, the action sequence of the use case that has the defect, and any interrupt or service request sequences that might influence the action sequence's outcome. Walk a peer through the sequence diagrams and see if they find anything missing from them.
4. Identify which modules of the software system are involved in the use case. Identify the source files that belong to those modules. Look through the files, assess their sizes, and see how long will it take for you to grasp them. You can review code at about 200 lines of code per hour, so it will take you about 5 hours to understand 1,000 lines of code, or about 25 printed pages.
5. Identify the most likely parts that you will be working on. What files will you have to change? Ensure that you can check those out of the revision control system. Setup a private branch for your fix to avoid disturbing other people's work.

By capturing a use case, a system diagram, and a few sequence diagrams you are well on your way toward understanding the system. These artifacts help you identify the root cause of the defect as well as provide you the starting point to devise and implement a fix.

There is more to understanding a system, but this is the minimum in order to improve your odds of success!