Assessing code, challenge one

As an architect that actually models software, you tend to think that the way that you, as the epic center of the software's design, and the ways you interpret the flood of information that is out there for the grabs, are the only reality. Keeping an open mind, continuously feeding it with new information and challenging your own ideas can be a tough job on it's own. That said, in my honest opinion, those loud people (we all met them at some point) out there that learned something in the past and stick to it with all their might, should not be working on the foundations of our software! Innovation is the key to improvement, self-innovation a logical consequence.

State the obvious

Let's be clear about one thing: Software is a product produced by 'normal' people. It is not some magical entity that at some point came to be out of thin air. It is the result of some intense thought-work that started a couple of decades ago and which still goes on! Regardless of the existence and usage of code generation, until someone invents an autonomous system (there are many movies about it, but it's still a mirage) writing and especially architecting software is going to be a creative process, done by clever people.

Motivation

Recently I have been granted the chance to look into the source-code of two loosely related software products, produced by two completely separated development teams. I was asked to review and assess (one of my next blog posts will be about that process) what was there, as both products had to be moved over to a new (3rd) development team.

 

It was fascinating to see, how both teams took a completely different approach and followed completely different architectural patterns to implement similar and/or equal features. For example, studying the diverse perception of what belonged in which architectural tier and how these tiers were then further segmented into different components, revealed a lot more differences than you'd expect.

 

During my most recent assessment projects, but also when working in/with disperse development teams in the past, I've re-learned that – and this is a Dutch expression – there are more roads that lead to Rome. Moreover, the various routes you might follow, are not necessarily all good or all bad. Basically, common sense and willingness to learn from others, and internet gives us that chance, combining the knowledge you can get with what you as the architect see fit and appropriate guarantees a unique application design that can be anywhere on a scale from 0 (bad) to 10 (good). It all comes down to your judgment, skills, insight and past experience.

The first challenge

When assessing other people's code – usually triggered by yet another party – and being asked to make judgmental calls by non- or less-technical people, they usually expect a good/bad verdict. The challenge is to explain to the client, that what they ask for does not exist!

 

In the past I've had a lot of hard times trying to explain the dynamics of software development/design and stressing that the outcomes of assessments and reviews are subjective. Sure, there are things you could say about implementations flaws, error prone code and (already less objective) good practices. But, when it comes down to arbitration and making recommendations regarding things like layering, segmentation, applied design patterns and separation of concerns, it's basically my word against that of the initial architect.

 

In my opinion, it is crucial that all parties involved are informed about the assessment being done. Also, it is often refreshing, to have all parties read the final report afterwards and merging responses into the ultimate assessment report. The biggest caveat is to 'work for the management' and see all your hard work either go down the drain or see it being used as a whip to punish development teams and architects.

So, what can be done?

My attempted solution to the problem is to manage expectation well from the start. It needs to be absolutely clear, that a second opinion is not to be seen as a final judgment. I do this by saying and writing things like (and this only works when stated with enough confidence and repeated more than once):

 

“I'm very honored that you are trusting my skills and experience enough to judge what is already there. Actually what that means is that you would trust me to architect the software from the beginning, if I was in the picture at that point in time.
I will do some fact-finding based on your own and/or often used guidelines and best practices. If needed, I could do some analysis of performance and stability using a profiler.
Keep in mind, that the recommendations section of the report, will be no more than the name states. It will be a summary of how I would have done things, if I was the initial architect and it will specify some possible actions to be taken which will improve what is there.”

 

I believe that this approach works, because it makes things explicit. Also, it sketches a clear outline of what the client may expect as an end-result. Nothing is worse than a client that expects way more than you can or intend to deliver. Dutch people are known to be direct and to Italians that sometimes comes across as rude. In this case, being explicit is the politest thing to do, because it will prevent needles and frustrating discussions in the end.