Four Techniques to Wrap Your Head Around Complicated Code


a step back and analyze them. Organize and structure the notes in a more disciplined manner. The most effective way is to create three sections: Known, Unknown, and Formulated Questions. Write down concepts that you understand clearly as bullet points in the Known section. Following this process, you will derive things that are unclear or not well understood; document these in the Unknown section. From this known and unknown information, you can formulate questions that you will direct at subject matter experts or research yourself at a later time.

This method is lightweight, fast, and extremely effective when you are wrapping your head around something complicated. It helps organize your thoughts, and the output is very direct, containing specific pertinent questions that get to the heart of the matter and eventually lead to a clear understanding.

3. FBI Board
The FBI board technique comes in handy when the previous, lighter techniques fail. It comes from watching some really good detective shows on television. In the television show, Flash Forward , the FBI is tasked with solving who caused a global blackout. In the other show, Dexter, a forensic specialist hunts down serial killers and is a serial killer himself.

In both shows, the protagonists set out to solve complicated crimes with a multitude of variables and circumstances. While thinking about the problem, they post all the facts and suspects on a bulletin board with thumbtacks. As more information relating to the crime comes through, they draw associations and possible outcomes.

How does this relate to software? You can use the same technique when you hit a brick wall and can’t figure out a problem. Take everything you know and lay it out in front of you on a whiteboard or some scratch paper. Stare at it for a while, and draw some relationships between items. Trust your intellectual powers to process the information in front of you, and let your creative juices flow.

On a government project that processed checks, I ran into a race condition issue where several transactions processed data concurrently. It seemed like the data entry disappeared into thin air after it was persisted to the database. I used the FBI board to enumerate all the moving parts. This helped me to qualify the scenarios, run some tests, and discover the problem.

4. Formal UML Diagrams
Unified Modeling Language (UML) diagrams have their purpose. When the goal is to communicate the structure of a system or a defined business process to many people, UML can be very valuable. UML is especially useful for understanding a large code base, even if it’s only to enhance the system with a relatively small change.

The most useful diagrams are sequence diagrams, class diagrams, and activity diagrams. In tandem, they offer both the structural and behavioral aspect of the system. Once you’ve taken the time to generate these diagrams, developers and business members can have a common visual depiction of the system to use as a base to solve problems.

Because generating these diagrams sometimes requires significant time and effort compared to the previous techniques, I recommend the UML diagramming technique when the lighter tactics come up short.

I had to resort to UML diagrams when working for a client that developed its own custom model view controller framework. The assignment was to add a simple upload page for a multimedia file. However, the framework had up to seven different layers with delegation and unnecessary code handoffs. It was so convoluted that it was difficult to understand the behavior without creating sequence diagrams. Every class was similarly named, and classes

About the author

AgileConnection is a TechWell community.

Through conferences, training, consulting, and online resources, TechWell helps you develop and deliver great software every day.