I once participated in a Python project in which we had to employ some pretty long and confusing data processing steps. In order to maintain the minimal modularity, we developed a system in which data would flow from one class to another through a very long chain. Each chain link would only need to know the calling interface of the the “next” step of the chain. This way we could test the overall process by testing interactions between those adjacent links (classes e/or modules) and at each “link” only the necessary, specific, processing logic. Note that the “long flow” was actually a domain logic/requirement.

In no time this structure led to a very, very unmaintainable code. The problem was that the flow chain was too long, rendering the processing logic impossible to grasp from a higher perspective (i.e. the big picture). Although we could clearly understand the adjacency steps, we could not see how data was being processed/modeled throughout the chain.

We decided then to use an activity diagram, in which we tried mapping the different program flows, decisions, method calls, etcettera. We chose an activity diagram for the fact that it allows you to go from in-procedure detail level to class level or communication/interaction levels. We could abstract when we needed to and we could dive deep into algorithm logic when necessary.

We used swim lanes to represent classes/modules, and within them we depicted as much details as necessary of what that class would actually do. The lines flowing from one swim lane to another would allow us to understand how classes actually communicated, and the lines inside the swim lane itself, how that specific class would do it’s own job.

In the end it wasn’t the most formal Activity Diagram, but it was actually good enough to ensure we could grasp the process from a higher perspective. This allowed us to comprehend better how our system interacted and to improve it, specially reducing the chain length.

After refactoring code and cleaning up the chain structure, we actually had to throw away the Diagram, since it was completely different and maintaining it would cause much work without many benefits. We would rather build up a new one whenever we felt the need for it, we used diagrams as a communication tool rather than documentation.

Whether or not that original chain-like design was adequate would be another matter. Anyway, after this experience I think Activity Diagrams are a good place to start if you wan’t to have a better view of your system/code for “cleanup” purposes. The main disadvantage is that it is hard to actually have a program structure (hierarchies, relations, etcettera) of your code.