Climb the mountain just a little bit to test that it’s a mountain. From the top of the mountain, you cannot see the mountain.
— Frank Herbert, Dune

Once, I was working with a colleague who was responsible for the storage subsystem. As typical in most cases, instead of developing the storage hardware, drivers and the file system, we reused such components as OTS (off-the-shelf) and implemented the additional requirements on our own. When something in the storage subsystem didn’t work as expected (e.g. bugs, insufficient performance), we had to sit down with my colleague and look at the components (reused ones as well as ours). And I often heard the argument that in order to be able to make a proper analysis he had to study the components in detail. However this would cause us to miss the release deadline, and kill our development budget.

This is a point that is difficult to argue, as there is uncertainty involved. No architect has the luxury of always making her decisions under full certainty. Beyond the facts that she could expensively collect, she has to rely on her past experience, maybe advice from colleagues and her gut feeling. To be able to make such decisions under uncertainty, the architect needs self-confidence and trust. Self-confidence comes from talent, experience and a sound, clear mindset; while trust will come from the organizational environment where it is encouraged to discuss & learn from failures instead of hiding them.

Empires of the previous centuries had similar challenges. They were very vast compared to today’s countries, and they had virtually nothing compared to the means of control and communication today. So unlike today they didn’t register every citizen, record every building and map out every street. When they conquered a country, they installed a governor and maybe some administrators, set terms on tax collection and military service and went away. So, they were conquering without invading.^[1]Gross oversimplification here, but I think the point is clear and hopefully historians do not take this blog seriously.

Hopefully the age of wars and conquests will be over, but we can still imitate the empires in conquering the code without “invading” it full-scale, i.e. without investing the high effort to understand every detail about the components, we can still handle them at a higher level that is necessary for our goals. This is a key architectural skill, as it gives us an economical way of working. Moreover it not only applies to OTS components^[2]Which is becoming increasingly challenging with the dizzying pace of innovation in frameworks and other technologies, especially in the web and cloud domains., but also to legacy components designed by people who are not around anymore, or architecture reviews where one has to get accustomed to new designs in a matter of days or even hours to be able to conduct a useful assessment.

So, how does an architect conquer code? It would take a book to provide a comprehensive list, but here are some hints:

• Tests: Surrounding the component with tests will help you in learning its interfaces, its behavior thereby requirements, and also provide a safety net if you want to change something in the components. As Frank Buschmann wrote, tests are an architect’s best friend.
• Diagrams (or documentation in general): Assuming you lack documentation, keep a continuously updated diagram with you during your analysis/reverse-engineering. This will help you as a map during your navigation and also keep you from diving too deep in the details and make you stay at the architectural level. Obviously you can refer to this diagram later as documentation, too.
• “Cuts”: Develop an hypothesis about the component and devise a test for this hypothesis. This will be your cut. For instance, you might state that the component includes a request queue that allows processing of multiple simultaneous requests. You can test this by sending multiple requests to the component and checking if it can handle it. Or you can make a focused review testing your hypothesis. You will learn about the component regardless of the success of your test, as the component will give a direct feedback to you. To be valuable, the cut should relate to the initial goals/questions you had, e.g. the system is underperforming as it can handle only one request at a time.
• Pattern matching: Arguably, this is the essence of all learning. As you do your analysis of the unknown component with the help of diagrams and tests, you will hopefully see some familiar patterns. Just as an enzyme accelerates a chemical reaction by orders of magnitude, patterns accelerate your understanding of the design. This is difficult, and I don’t know how to dissect this process further. In general, you need to know a lot of patterns which you can accumulate with experience, and to my experience some people have an “eye” for seeing patterns right away, while others need some more time.

Of course, using these techniques, one can also go too deep into costly analysis. It is key to stay focused on the goal of your analysis and also have self-confidence and trust to avoid that.

Always interested in your feedback, please leave a comment.