Naming

(or how names can be ambiguous)

I've done a bunch of software architecture sketching sessions with teams over the past few months and, although we cover a lot of ground, here's a tip to improve your diagrams. If naming is one of the hardest things in software development, resist the temptation to have a diagram full of boxes that only contain names.

A really simple way to add an additional layer of information to an architecture diagram (and to remove any ambiguity) is to annotate boxes with a very short statement of what their responsibilities are. A bulleted list (7 ± 2 items) or a short sentence work well. Provided it's kept short (and using a smaller font for this information can help too), adding responsibilities onto diagrams can help provide a really useful "at a glance" view of what the software system does and how it's been structured. Here's an example ... which diagram do you prefer?

Naming

If you're interested in how to sketch software architectures, you can...

Happy sketching!

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 simonbrown.je for information about his speaking schedule, videos from past conferences and software architecture training.



Re: Naming

The one on the right. Amazing how simple details can make a difference. Keep up the good work Simon.

Add a comment Send a TrackBack