The Small Diet Coke: Coupling and Requirements

August 26, 2016 — Posted by Scott Bain

When considering the quality of a design one of the things we focus on is the coupling between entities.  Coupling is both necessary (you create a system’s behavior by coupling entities to each other for collaboration) and often problematic (excessive or illogical coupling produces unpredictable side effects when changes are made).

So, clearly, some coupling is good and some coupling is bad.  The terms we traditionally use are "tight" for the bad coupling and "loose" for the good... however, this does little more than label the identified coupling as one or the other.  It does not tell you why.

One insight that comes from code reviews and coaching is that coupling which a developer intentionally introduces into the system, which has a defined purpose and which the developer can explain logically is generally good coupling.  It was placed there on purpose for a well-thought-out reason.  We rarely do wrong things on purpose.  On the other hand, coupling that was put in place without any intention, due to an honest mistake, is generally the coupling that causes problems: nobody wanted it, it does not have a useful function, and often we don't even realize that it is there.

One source of this kind of unintended coupling is the way requirements come to us.

Generally speaking requirements are expressed using colloquial language.  People tend to speak and write the way they think.  This can lead to a syndrome I call "The small diet coke."

You're standing in line at a sandwich counter.  When your turn comes you ask for “a bagel and a small diet coke.”  This seems like a very clear and unequivocal statement of your requirements for lunch, but you have delivered the drink requirement with hidden coupling inherently pre-packaged into it.

There is no such thing as a small diet coke.  What you mean is you want a small cup of diet coke.  The cup is small; the coke is not. Beverages do not have size; they have flavor and other characteristics like effervescence, temperature, viscosity, color, etc… containers have size.

We model a system based on our view of it.  If I was creating an object called “Diet_Coke” and gave it a “size” attribute, this would introduce coupling between the liquid and the container it is placed in, when in fact the same liquid could be placed in any number of different containers, and thus should not be coupled to the current one.  Instead I should create the correct coupling: the cup, which has size, contains the liquid, which has the other characteristics.  The container dictates the maximum amount, etc....  Other containers could also contain this liquid, and this same container could contain different liquids.  This results in a flexible design and it also based on the logic of reality.

Here is an example that is less abstract:  Imagine you are creating an online store for selling physical goods through the internet.  You will have people logging in and making purchases from different locations around the world, and this will produce many different variations.  You will have to accommodate different currencies, charge sales tax using different calculations, perhaps localize the text on your pages for different languages. 

A business analyst might tell you, for example, that your European customers will interpret a date differently than your US customers.  The date “1/6/2016” to a European means “June 1st”, whereas to a US customer it means “January 6th”.  So if you tell your US customer when to expect his package to arrive and you “use the European date format” he’s going to complain when his package is five months late.  You have to “use the US date format” when communicating with a US customer.

This requirement, if stated this way (which is not hard to imagine) would lead you to believe that there is such a thing as the “US date format.”  There is not.  I live in the US and do not use that format; I prefer 2016-06-01 for January 6th because of the way it sorts.  I’m a nerd.  Anyway, nobody has ever arrested me or fined me for living and working in the United States and failing to use the prescribed date format, because such a thing does not exist.

The truth is that there is “a date format which is commonly used in the US”.  If I know my customer is in the US, and I have a menu of date formats for him to choose from, I’d probably put the month-first version at the top of the list, or have it pre-selected for his convenience.  But that does not make it the “US date format”.  He should be able to choose another if he likes.

There is, on the other hand, a prescribed format for phone numbers.  In the US the phones (land lines) work the way the infrastructure says they work; if you put “0-001-425-269-8992” on your business cards and hand them out in the US simply because you prefer the European way of structuring a US phone number, you’ll never get a phone call because everyone will end up calling the operator instead.

Does this mean that assigning “size” to a beverage is an inherently bad design?  Not necessarily.  But doing so without applying critical thinking may lead to a bad design, may lead to coupling that you create without realizing you have done so, and this is the coupling that typically causes maintenance headaches.

We need ways to strip away all the hidden coupling that comes from the way requirements are expressed to us, so that at the end of the day all of the coupling in the system is that which we have intentionally put into it: the good kind.  The kind we know about and which will be logical to others.

In other blogs, both here and at our TDD blog site (, we have and will continue to examine various techniques for accomplishing this.  A good example is a recorded webinar outlining an analysis technique we learned from James O. Coplien in his thesis “Multi-Paradigm Design”.  It is called Commonality-Variability Analysis, and is one of the many skills we teach in our design patterns and test-driven development training.

This is a great example of what I mean by “applying critical thinking” to requirements and is a really good place for you to start.

Subscribe to our blog Net Objectives Thoughts Blog

Share this:

About the author | Scott Bain

Scott Bain is an consultant, trainer, and author who specializes in Test-Driven Development, Design Patterns, and Emergent Design.


Blog Authors

Al Shalloway
Business, Operations, Process, Sales, Agile Design and Patterns, Personal Development, Agile, Lean, SAFe, Kanban, Kanban Method, Scrum, Scrumban, XP
Cory Foy
Change Management, Innovation Games, Team Agility, Transitioning to Agile
Guy Beaver
Business and Strategy Development, Executive Management, Management, Operations, DevOps, Planning/Estimation, Change Management, Lean Implementation, Transitioning to Agile, Lean-Agile, Lean, SAFe, Kanban, Scrum
Israel Gat
Business and Strategy Development, DevOps, Lean Implementation, Agile, Lean, Kanban, Scrum
Jim Trott
Business and Strategy Development, Analysis and Design Methods, Change Management, Knowledge Management, Lean Implementation, Team Agility, Transitioning to Agile, Workflow, Technical Writing, Certifications, Coaching, Mentoring, Online Training, Professional Development, Agile, Lean-Agile, SAFe, Kanban
Ken Pugh
Agile Design and Patterns, Software Design, Design Patterns, C++, C#, Java, Technical Writing, TDD, ATDD, Certifications, Coaching, Mentoring, Professional Development, Agile, Lean-Agile, Lean, SAFe, Kanban, Kanban Method, Scrum, Scrumban, XP
Marc Danziger
Business and Strategy Development, Change Management, Team Agility, Online Communities, Promotional Initiatives, Sales and Marketing Collateral
Max Guernsey
Analysis and Design Methods, Planning/Estimation, Database Agility, Design Patterns, TDD, TDD Databases, ATDD, Lean-Agile, Scrum
Scott Bain
Analysis and Design Methods, Agile Design and Patterns, Software Design, Design Patterns, Technical Writing, TDD, Coaching, Mentoring, Online Training, Professional Development, Agile
Steve Thomas
Business and Strategy Development, Change Management, Lean Implementation, Team Agility, Transitioning to Agile
Tom Grant
Business and Strategy Development, Executive Management, Management, DevOps, Analyst, Analysis and Design Methods, Planning/Estimation, Innovation Games, Lean Implementation, Agile, Lean-Agile, Lean, Kanban