The code doesn't tell the whole story

We all know that writing good code is important and refactoring forces us to think about making methods smaller, more reusable and self-documenting. Some people say that comments are bad and that self-commenting code is what we should strive for. And I don't disagree. Everybody *should* strive for good code that's easy to read, understand and maintain. But the code doesn't tell the whole story.

Read the full essay...

About the author

Simon is an independent consultant specializing in software architecture, and the author of Software Architecture for Developers (a developer-friendly guide to software architecture, technical leadership and the balance with agility). He’s also the creator of the C4 software architecture model and the founder of Structurizr, which is a collection of open source and commercial tooling to help software teams visualise, document and explore their software architecture.

You can find Simon on Twitter at @simonbrown ... see for information about his speaking schedule, videos from past conferences and software architecture training.

Re: The code doesn't tell the whole story

I have found myself in this situation many times and I'd say that I've spent more time browsing through code than writing it. One thing that strikes me is that IDEs are good at helping you write code but not so good at browsing through (large amounts of) code. This is partly a failing of the IDEs (jumping between sections and retracing steps is slow) but mainly (as you say) code's poor ability to capture higher level concepts.

It's a bit like trying to work out what a building is used for by examining it brick-by-brick. This is why structural architects use blueprints/drawings and so should we!

Re: The code doesn't tell the whole story

Agreed and if those blueprints were available, we wouldn't have to resort to software archeology!

The code *does* tell the whole story - but you might not want to hear it

i agree with most of your statements - but not with your conclusion that "the code doesn't tell the whole story".

instead, i suggest that the issue is that the code indeed *does* tell the whole story (if we include configuration files, deployment scripts, DB scripts, etc. in the definition of code): if one reads the complete code-base of a system one gets a complete picture of the system, because all behaviour of the system can be derived from the code. but doing so is normally impractical, inefficient and may well be prone to misinterpretations. the code embodies the architecture but doesn't usually make all aspects of the architecture explicit. so we need an architecture document that abstracts from the code, outlines the underlying principles, and in general gives a simplified and accessible introduction to the system - with the full detail being available in the code.

a good analogy, to keep your "story" metaphor, is between code and the text of a novel; and the architecture document and the synopsis of the novel: code and text both tell the whole story, but you'd have to actually read them to form an accurate opinion. architecture document and synopsis hide details of the underlying code/text but expose the important bits (hopefully).


The code *does* tell the whole story - but you might not want to hear it

I see where you're coming from and you're right in that the code embodies the architecture. It does. For me though, the code can't give you the "why" (e.g. rationale behind decisions) and some of the "how" (how is the system actually deployed? how does failover work? how is DR catered for? etc). From this point of view, the code tells most of the story (and it doesn't make all aspects of the architecture explicit) but (for me anyway), not the whole story.

Add a comment Send a TrackBack