Marco Valtas

You start on a new project with a team that is working on a code for some time. Credentials for the repository are given, you check out the code and two minutes after your inner voice goes “Oh my god, what happened here?” This can be the unsparing sole dev bias talking.

While possible with context, there’s a mixture of Fundamental Attribution Error and Naive Realism when you do it without context. The idea that just reading code without other information is sufficient for assessing its “goodness” is problematic as concluding that a book is bad by reading one random page. ¹

The bias is to assume, as you evaluate the code, what you would write alone under no constraints. This mistake leads to an unrealistic bar from which the code is being evaluated. A more balanced frame of mind can be: What code could this group produce under certain constraints?

Figuring out what “certain constraints” actually represents is the key. The code is seldom written by someone alone with all knowledge and time to solve the problem. The environment in which most software is produced is much more complex. Before already visualizing a “better version” you can start by asking some questions:

• How many people changed this code? Although most teams try to get a consensus on style, language use and etc, this is hard. Sometimes code lives through generations of programmers and leadership. What you are looking at is more a patchwork of opinions and styles than an elegant solution to a problem.
• Did I consider environmental constraints? What degree of freedom the team has? Is this a safe environment for learning? If not, expect several guard clauses and duplication.²
• Is this a rewriting? Rewriting have a tendency of copying the structure of the old for several reasons.
• What’s the Conway’s Law effect? Communication structure between team members and other teams influence code structure.
• How the problem was framed to the team and how it changed over time? Problems change and we all know that. The question is how and when the change was discovered by the team.

I bet you can think on a lot more questions and this is the idea. We should hold our first impulse of qualifying code and team just by a glance at the code. By asking these questions your assessment will use a more realistic bar and you can start searching for solutions (of the real problems) under the same constraints the team has.

PS: The day I decided to publish this post I received an email from Pragmatic Programmers announcing a new book Software Design X-rays, Fix Technical Debt with Behavioral Code Analysis and I got my copy already.