Yesterday I finally got a tricky bit of code working. It’s a spike, helping me to figure out how a complicated distributed algorithm will all hang together.

And when I say “working”, I mean that it worked on my laptop :-). I tried deploying it to my production server and it didn’t work there. But that’s because part of it makes a post to http://localhost:44002, which doesn’t exist in production. Not a surprise.

So my job for the next few cycles will be to expand on this code, removing the assumption about where it runs. Notice that I said “expand” rather than “fix”. The code isn’t broken. It definitely works, but only under certain circumstances. It is tested, but it includes an assumption. So I consider the job of the next few cycles to fall into a bit of a grey area between feature writing and refactoring, and here’s what I plan to do…

My domain model — and my architectural assumptions — tell me that I should be getting that URL from user profile data held elsewhere in my network. And in fact there should be a list of such URLs, instead of just one as in the current spike. That is, I’ll need to replace that hardcoded string “http://localhost:44002“ with an API call that should return an array of profiles, each of which includes an attribute whose value is the appropriate URL. That API call could also fail. So I’m planning to replace a string value with a call to an endpoint that will return some sort of Promise of either a list of profiles or one of several kinds of error. Oh, and that endpoint doesn’t yet exist.

I’ll outline my plan below, but before continuing, maybe take a moment to think about how you would approach this while keeping the code working…

I could start by writing the new endpoint. After all, I “know” what its signature should be. But then it will sit around, not being called, while I reshape the current code to cope with errors, arrays, profiles, and promises. The client-side code knows about none of those things currently, and they each represent a little risk to the application’s current fragile working state.

So instead I plan to do the opposite. I’m going to apply the following refactorings, possibly in this order, possibly not:

1. Wrap the hardcoded URL in a function call. This gives it a name, which will help me to remember why it exists. And it creates a “seam”, hiding some of the details of what happens next.

2. Refactor the client to have an array containing the single hardcoded URL. This will force the downstream code to deal with multiple URLs, but the code will be easy to keep working.

3. Wrap the hardcoded URL in a user profile object, so that my client-side code knows how to unpack such a thing, and so that I know what it needs to look like.

4. Wrap the hardcoded data in a Promise and test for error conditions. I don’t really know yet what that looks like, and I expect I’ll have to revisit this once the API call is being made for real.

Each of these refactorings should result in code that still works, and can be committed to main without changing existing behaviour. Now, finally, I can write a simple API endpoint that just returns exactly the same hardcoded data (an array containing a single made-up profile whose URL is still the hardcoded localhost value), and call it from the client. At this point I’m making the network call, and the code dealing with Promises and errors is being exercised. If all goes to plan, this is still releasable with no change to current functionality.

Something very important has now happened, though: I’ve pushed the hardcoded value back towards where it will eventually originate — without changing any existing, tested functionality. The hardcoding is now inside the server API endpoint, and no longer in the client. The client has been generalised, and should in future just do what the server tells it to do.

This is the essence of outside-in development, and the foundation of the Mikado method too. Each cycle pushes an assumption towards an edge of the application until it disappears. Each cycle can be committed to main and deployed. And all the while, the entire application keeps working.

Does your team work this way? If not, and you would like to learn how to apply outside-in development in your work, message me and let’s chat about whether some of my training or coaching could work for you.

I’m going to take a break for the next couple of weeks.

And before I do that, I want to ask you a question: Is this kata series useful enough to continue, or would you prefer me to revert to the more varied content I created previously?

On the one hand, these articles give us a chance to dive deep into writing code via TDD and refactoring. By taking the time to unpick even the tiniest moments, I’m finding a surprising amount of design thinking to discuss. Admittedly the code isn’t changing particularly quickly across these articles — but that’s because each week I’m expanding a few seconds’ thought into a thousand words of analysis and exploration. And in the course of that expansion I’m discovering heuristics that even I didn’t realise were in play. You can find a list of many of them at the end of this article, as a kind of recap of what I’ve learned from the 7 articles so far.

But on the other hand, this one very simple example is taking a loooooong time to go anywhere, and it shows no signs of finishing any time soon. So by focusing so deeply on such a simple example we’re losing the opportunity to explore more widely. I have ideas for other katas too — for example following the lead of Kent Beck’s book Test-driven Development by Example by TDD-ing a unit testing tool, or doing something in a functional language, or trying the auction sniper kata from Freeman and Pryce’s Growing Object-Orient Software Guided by Tests. There are also more general discussions to be tackled, such as continuing to explore specific cases of implicit coupling in more of a “solution catalogue” style.

There is a lot to explore, yet I only have 2 hours per week for writing. So where should I focus?

To provide a little more context for your decision, I’ve collected together below all of the “Things to try” sections from this series of articles so far. This list represents a whole bunch of things I tend to do instinctively, without thought, but which have occurred to me consciously because I’m writing these articles. I hope you find them useful!

1. Take half an hour to do a (different) kata using the TDDAIYMI style. What did you learn about your usual programming style? Or about how much “design” you do without consciously calling it out?

2. Make a list of problems you can see in your own code, and prioritise them according to the 4 Rules.

3. Make sure the names you use in the code reflect the vocabulary you use when talking about that code.

4. Find a place where your code doesn’t tell the story you and your Customer intend; refactor until it does.

5. When you’re assessing whether your code tells its story, start at the outside and work inwards only when the outer layers of abstraction communicate extremely well.

6. Next time you have to refactor, consciously cycle around the 4 Rules. In particular each time you change anything, start again with a new review of the names and the story they tell.

7. Take a break after any period of concentrated effort. When you return you’re likely to see things with fresh eyes.

8. Next time you’re getting from RED to GREEN jot down as many alternative code changes as you can think of. Which one do you choose to move forward with, and why?

9. Look for opportunities to increase the symmetry and self-similarity in your code. Does this always help with readability?

10. Next time you have a choice between depth-first and breadth-first tree walking, try breadth-first and look out for symmetries appearing sooner.

11. Explore property-based testing: is it appropriate for the code you’re currently writing?

12. Find a function in your own code that has two parameters of the same type. Try following Fowler’s mechanical steps for Introduce Parameter Object. How did that feel, compared to using an IDE to accomplish the same thing?

13. Look for places in your own code where you could increase the symmetry. What happens to understandability when you do?

14. Do the names used inside your functions reflect the function’s internal context, or are they coupled to the names used by the callers?

15. Before you add the next test, make an explicit list of the implicit coupling you can see in the area of code you’re working on. What should you fix before proceeding?

16. Think about how you decide whether to prioritise new functionality or refactoring. What kinds of coupling do you defer, and why?

I hadn’t realised there were so many!

This is how we left things last time:

Coming back to this code after a couple of days away, I have the scary feeling that I’ve let a few problems build up. Before I continue, make a note of which violations of the 4 Rules you can see.

Leave a comment

What I see (in no particular order) are these:

1. totalPriceOf still has two parameters, and the caller can’t know which order they should be passed.

2. By changing the price list keys to match the product names, I introduced those product names into the code of the function. It shouldn’t know about them.

3. The code and the test are coupled together by the two assumptions that prices are expressed as integers and product names/keys are expressed as strings. (This is Connascence of Convention, aka Connascence of Meaning; in code smell terms we might call it Primitive Obsession or Open Secret.)

I now have to make a decision: do I address any or all of these, or do I move on to add the next test? This is the kind of decision I — and all of us — make numerous times each day, often instinctively and with little or no conscious thought. Sometimes we’ll rush forward with the next test, sometimes we’ll fix whichever of those smells we’re attuned to on that particular day. Does it matter? Is there a “best” thing to do here? Or will we always converge on the same design eventually, regardless of which route we take?

A big part of me wants to move forward with the next test1. That's because I often like to allow the problem to get a little bigger before I clean up. As this code grows and evolves, the coupling I identified above will grow and evolve too, and often the solution patterns become easier to see when their "surface area" is larger. Or maybe I'm kidding myself here: perhaps I just simply enjoy solving bigger, hairier problems, and so I have a personal incentive to let the coupling get out of hand before tackling it.

Part of me also thinks that fixing these smells now could be gilding the lily: maybe I don't yet have "enough" code to be worrying about coupling -- after all, it's only 25 lines and I can see all the way across it from end to end. Surely I need more code to make the refactoring worthwhile?

Running counter to these thoughts, this series of articles is about refactoring, and so I am going to address those smells before moving on. Would I do this in “real life”? Let’s answer that case by case:

1. I feel that the two parameters to totalPriceOf play different roles in our story, because they change at different times. I can imagine — although I would need Customer confirmation of this — using the same price list to cost numerous baskets of items. And in fact the metaphor I unconsciously used in that previous sentence might suggest asking the price list to cost the basket2. Whichever way I choose to tackle this, I’m going to be altering the tested API. So I want to do that soon — partly because the code is small now and so there’s less to change, and partly so that I get early feedback on whatever design I choose. I’m going to fix this one now, to maximise my learning and avoid the potentially higher cost of doing it later.

2. In order to eradicate knowledge of the product names from the code I suspect I will have to rewrite the algorithm. And with only the two tests I have currently, that feels like a risky enterprise. So I will leave this smell in the code until I have more tests — and maybe the addition of those tests will drive out those algorithm changes anyway.

3. In Javascript I don’t have static types, and so it’s really not obvious how best to cope with these assumptions about primitives. I guess I could wrap the integers, strings and arrays in objects of specific classes, and doing so would make those types explicit in the caller. Would that be too clunky, making the caller’s code less elegant and expressive? Well, given that I’m going to change the tested API anyway, maybe this would be a good thing to fix now too.

So I talked myself into immediately fixing two of the three problems I’ve identified, and while doing so I realised that there was one more example of Connascence of Convention that I hadn’t noticed earlier. Making lists turns out to be a valuable exercise yet again!

Does it seem as if I’m over-thinking all of this? What I’m trying to do is to unpick those micro-decisions we all make without much thought. Next time, I promise I’ll actually do some refactoring 😊.

Things to try

• Before you add the next test, make an explicit list of the implicit coupling you can see in the area of code you’re working on. What should you fix before proceeding?

• Think about how you decide whether to prioritise new functionality or refactoring. What kinds of coupling do you defer, and why?

As always, please leave a comment if you try any of these.

And finally…

Just a quick mention that I recently recorded an episode of the Mob Mentality podcast to talk about rhythm and cadence in both ensemble programming and TDD. The podcast is on YouTube:

Last time, I decoupled the code from the prices of A and B.

Currently on the branch we have this code:

The tests pass, so I move straight on to readability — does this code tell the domain’s story clearly? I’ve not looked at this code for a couple of days, and so I’m reviewing it again today with somewhat fresh eyes. What jumps out at me right away is the two length checks on lines 3 and 5: based on what we know of the domain, they surely can’t stay like that for long (in the “real world”, not every shopping cart that has only one item will contain an A, for example). But I’m shooting for TDD, and right now I don’t have a test that requires those checks to change. They currently do the job I need them to do, and I know I can rely on future tests to drive out a more realistic algorithm.

This is an interesting point of tension, particularly for folks who are new to test-driven development. We “know” that the current code is an incomplete representation of the “real world” domain. But it is also the simplest way to make the current set of tests pass. So the code is in fact a highly faithful model of the domain as defined by the tests. That’s an important distinction: there are two domains in play at any moment. The current set of tests defines one domain, and we’re gradually incrementing that to be closer and closer to the “real world” domain.

On another day I could be easily tempted to say that those length checks are so obviously “wrong” that I would immediately look for another test or two to allow me to drive them away. That would definitely be a legitimate course of action, and there’s a lot to discuss in regard to the idea of deferring a few REFACTOR steps. Remind me to come back to that concept in a few weeks? But the purpose of this series is to push hard on refactoring away the coupling as soon as it appears, so let’s move on to that next.

(Another interesting point — at least for me — is that I wasn’t expecting to talk about this topic today. I don’t have a plan for this series of articles, and so I’m being completely carried along by the current. Whatever I see today is what I put down here. It’s not quite stream of consciousness, but I’m finding this level of deep introspection quite fascinating. I hope you’re enjoying that aspect too…)

And so on to rule 3. Does anything in this code violate Once And Only Once? I don’t think so. And yet there is Connascence of Position, because nothing prevents the caller from passing those three arguments — items, priceOfA, priceOfB — in the wrong order. This is exactly the situation I unpicked in Functions with Multiple Parameters a couple of weeks back: there is no way to write the caller’s code such that it is obvious which is the correct parameter order.

So, following my own advice from that earlier article, I’m going to replace the pair priceOfA, priceOfB with a containing structure:

The tests pass, so I commit: Replace two parameters with a structure.

I want to note a couple of things about this step. Firstly, aficionados of code smells might call this Long Parameter List. And in my book1, our recommended remedy is to use Martin Fowler’s Introduce Parameter Object refactoring. Here, I have no evidence (yet) that an object is necessary, so a structure will suffice.

And secondly, this still leaves the function having two parameters. And because Javascript offers no static types in the source code, I still can’t know in the caller which order is correct. So I’ve improved the situation a little, but not yet completely eradicated the problem.

But first, I made a change and so by the rules of these articles I have to go back around the 4 rules of Simple Design. The tests pass (rule 1), but does this code express everything in the best way possible (rule 2)? Well, it seems to me that prices.priceOfA is not only clumsy but also contains duplication. Instead I can use the product name as the key into the lookup table:

The tests pass, and I’m happy that this expresses my intention. Commit: Improve relationship between prices and products.

I note that Javascript would allow me to say prices.A at line 4. But prices[‘A’] expresses my intention better, I feel, because of the symmetry with line 13. If the product name contained spaces, or weren’t a string, the approach I’ve used is the only workable one; but even in the simple current case I prefer the approach of expressing the lookup key in the same way everywhere it occurs. I’ve noted before that self-symmetry is a powerful tool for me: symmetries make the code easier to read (maybe something to do with having less to remember?). Symmetries also offer clues to various kinds of coupling, so I seek them out and highlight them whenever I can. So even though my programming language offers me a more succinct, idiomatic, option I prefer to expose the symmetry and express the domain a little more faithfully.

And so let’s look again at how well this code tells the story my Customer told me. I just introduced the name prices, so I re-read all of those changed lines. There’s something not quite right in the story-telling, and I finally spot what it is. The little structure defined on line 12 doesn’t just contain prices, so the name is wrong. And looking at line 22 I can now see that priceList would be much better:

That feels much better. Commit: Express the domain more clearly.

Two thoughts strike me now, both triggered by making that change. Firstly, that structure obviously isn’t a “list” in the data structure sense. But that is what we tend to call them in the real world. Could that cause confusion? Only if the reader brings along with them expectations of programming style. Because shoot me if I ever include a language type in the name of a local variable or constant. Hungarian notation creates coupling between implementation and intention, so it’s generally a bad idea. And as with prices.A above,

whenever there’s a conflict between expressing the domain and writing idiomatic code, the domain should win every time.

Secondly, I chose to change the name in both the code and the test, even though they are strictly independent of each other.

But I can’t think of different names that might work better, so I’m happy to leave it for now. Something to be mindful of as we proceed, maybe.

Next time: is it time for the next test, or do those references to product names (lines 4, 6, 12, 13) represent coupling that we want to fix?

Things to try

• Find a function in your own code that has two parameters of the same type. Try following Fowler’s mechanical steps for Introduce Parameter Object. How did that feel, compared to using an IDE to accomplish the same thing?

• Look for places in your own code where you could increase the symmetry. What happens to understandability when you do?

• Do the names used inside your functions reflect the function’s internal context, or are they coupled to the names used by the callers?

As always, if you try anything here please let your fellow readers know how it went by leaving a comment.

Leave a comment

Last time I decided to compare two different approaches to test-driving this kata. We’re currently working on a branch while we explore triangulation, and then we’ll go back to main to explore the alternative approach of fixing the coupling first.

Currently on the branch we have this code:

I’m satisfied that this tells the Customer’s story well enough for now, so it’s time to move on to rule 3 and look at coupling issues. A quick glance shows me the following:

1. The price of an A is 50, which is known by lines 4, 14, and 15.

2. The price of a B is 30, which is known by lines 6 and 15.

3. Lines 3-6 are coupled to the lengths of the test arrays somehow.

There may be more, but I don’t feel it matters if we don’t see it all now. After we’ve done some cleaning up we’ll regularly look at the code again and again, and I think we’ll be more likely to spot other coupling (if it’s there) when we have somewhat cleaner code.

So, which to fix first. Again I’m not sure it matters, so I’m going after that 50, simply because it’s the most obvious.

The value 50 is arbitrary, but something somewhere must know it; so we can’t remove it altogether and it needs to be defined somewhere. So I can see five options:

1. Define the price of A in the code and let the test access it.

2. Define the price of A in the test and let the code access it.

3. Define the price of A in the code and pass it to the test.

4. Define the price of A in the test and pass it to the code.

5. Define the price of A somewhere else and access it from both the code and the test.

Options 2 & 3 would create a dependency from the code to the test, so we rule them out right away. Option 1 violates the intent of the kata (the pricing rules should be easily changeable without changing code). And for option 5 I don’t yet have anywhere else available. So option 4 feels the lightest touch for now.

I add a parameter:

The tests pass, so I commit: uncouple the code from the price of A. And to stick with my intended discipline, I now return to the 4 Rules again.

Does this code express my intention? Actually, for now I think it does, so I move on to rule 3 again. The code is now explicitly coupled to the price of A, which is a clear improvement; but it is still implicitly coupled to that 30 for the price of B. And what do you make of the several places in the test that mention 50? What would you do about that? Take a moment to consider the options before reading on — and please leave a comment explaining your reasoning if you have the time.

Leave a comment

My preference is to leave the test as it is — at least for now — for a couple of reasons. Firstly, all of the 50 instances are now in one function; so although lines 14, 15, and 17 are implicitly coupled together, they are all within a single encapsulation unit and so the risk of something breaking is low and the cost of fixing it is also low. We should make a mental note to review this decision if the test gets much bigger, or if it gets broken up into helper functions or suchlike. But for now, the potential problem is contained and localised, so I’m not concerned about it.

Secondly, I feel there’s more mileage in addressing the coupled 30 instances first. Because when I’ve done that I may begin to see patterns of similarity that link the 50s and the 30s, so my next round of refactoring could have more information to build on. That is, if I fix similar problems twice in a row (the 50s, then the 30s) I’m hoping I may have more self-similarity to shoot for afterwards; whereas if I press on with the 50s I may not see some nice symmetries until I’ve expended a lot of effort. In general I have a preference for breadth-first tree walks — fix the 50s a little, fix the 30s a little, fix the 50s a little more, fix the 30s a little more, see the patterns that emerge, …

But there are trade-offs here, as always. Let’s imagine for a second that I “fix” the duplication by defining the price of A in exactly one place:

Line 17 gives me cause for concern, because now it explicitly duplicates the algorithm from the code. Look ahead at the remaining tests in the kata and you’l see that later test cases will become more and more complicated and I’ll have dozens of lines of test code that effectively duplicate the code’s algorithm. So I have to make a trade-off: do I explicitly document how the test values were derived, or do I explicitly document the expected outcomes, and expect the reader to do the calculations in their head? The second variant above would have the advantage of allowing me to replace the static 50 with an arbitrary — maybe even randomly generated — value. I feel that would give me better coverage, and would be a step on the road to property-based testing this code. So maybe as the forces within this code change I’ll reconsider, but right now I like the clarity of having the explicit 50 in the test expectation.

Reverting back to the committed code, I make a similar change and inject the 30 as a parameter:

Commit: uncouple the code from the price of B.

As per usual, it’s now time to sit back and reflect on how well this code tells its story, and whether I’ve introduced any (more) implicit coupling. For example, we can now clearly see additional symmetries caused by the introduction of priceOfB. Do they help us or hinder us in understanding the code? What would you change next?

Things to try

• Next time you have a choice between depth-first and breadth-first tree walking, try breadth-first and look out for symmetries appearing sooner.

• Explore property-based testing: is it appropriate for the code you’re currently writing?

As always, if you try these please let me and your fellow readers know.

Leave a comment

Last time I spent quite a bit of effort getting my code and tests readable (in the sense that they tell my Customer’s story). I arrived at a point where I felt it was time to introduce the next failing test, but I promised to review the code one last time before making that big step.

So here's where we are right now:

Coming back to this now, I can see that there’s still some coupling that I should address.

Firstly, zero appears three times (lines 2, 3, and 11). The instance on line 3 is clearly unique, but those other two “mean” the same: they represent the price of an empty basket. In past attempts at this kata I’ve never bothered about that, but I can definitely conceive of situations in which there could be a non-zero fee for engaging the purchasing process — perhaps a membership fee or reservation fee. But looking ahead at Pragmatic Dave’s tests I can’t see any mention of such a thing for this kata, so I’m happy to let those zeroes stand as they are.

Am I “allowed” to look ahead? I think so — I suspect that’s what my Customer is doing much of the time. But what about YAGNI (You Ain’t Gonna Need It), I hear you cry? Well, I’m not deciding whether to add functionality; only how much to refactor. In terms of implicit coupling, I guess I’m deciding that it’s okay for the zero starting price to be implicit in this codebase, and that adding a constant or suchlike would be overkill based on what we know now. I don’t want to pre-load this code with every future I can possibly think of, and so I’m happy for now to assume that what we can see in the future tests is all we’ll have to cope with.

Next though, there are 50s on lines 4 and 12. This feels like an arbitrary value, and the kata description ends with this paragraph:

“The challenge description doesn’t mention the format of the pricing rules. How can these be specified in such a way that the checkout doesn’t know about particular items and their pricing strategies? How can we make the design flexible enough so that we can add new styles of pricing rule in the future?”

So my instincts are borne out by the Customer: the 50 is an arbitrary value and represents unwanted coupling between the code and the test. And I’d say that the coupling is implicit, because I see nothing in the totalPriceOf function that tells me how the 50 is likely to change.

The question is, what to do about it? As I’ve mentioned elsewhere, some folks would triangulate here, adding another failing test that demonstrates the coupling. Indeed many times in the past I’ve added a new test

at this point. Pragmatic Dave takes a slightly different slant on the same idea:

Me, I’m always nervous about triangulation. I don’t like the thought of adding more complexity to code that is already coupled — it seems like an added maintenance burden and we still need to fix that coupling.

But that’s a purely subjective view, so let’s put it to the test. At this point I’m going to branch: I’ll triangulate on one branch and then come back to trunk and fix the coupling instead of triangulating. Then we can compare the two approaches and see what benefits each gave us.

So I create a branch triangulate-first and add Pragmatic Dave’s next test. It fails, so I quickly make it pass:

Commit: calculate price for basket with A and B.

There are, of course, plenty of ways I could have changed the code to make this test pass, so why did I choose this one? I don’t honestly know. I also considered something like this:

Both variants have the advantage that they are pure additions, leaving the code around them unchanged. And arguably the second variant is a direct, naive interpretation of the new test, whereas in order to get to the first variant I must have done subtraction in my head. So in some sense the “distance” from the new test to the second variant is shorter, and maybe that’s a better habit to have.

That said, the option I chose does reflect the pricing rules from the original kata description (the price of a B is 30). More importantly though, it also extends the structural pattern of the original code. I think I have a strong personal preference for designs that are expressed through symmetry and self-similarity. This may also be why I like my test cases organised in a table. Nevertheless, I took a design step while getting from RED to GREEN, and in general I try to caution against doing that.

Anyway, we are where we are, so let’s stick with it and see where it takes us. It’s time to refactor. Following the 4 Rules, I need to start with readability. And if I want to tell a story I should begin at the outside — in this case that means with the tests. I didn’t change any names, but I did violate the layout we introduced to help deal with all those brackets. So I change lines 13-14 to return to that standard:

This is probably going to become tiresome, so I may need to think of something better if it does. Commit: ensure consistent layout of test cases.

I feel those tests are (still) pretty readable, so let’s look at the code. If I forget everything I know about future requirements (ie. the remaining tests in the kata description), then the code as it stands seems reasonably clear. I can’t think of a way to improve its story-telling ability.

So I feel it’s time to move on to rule 3 — does this codebase say everything once and only once? We’ll find out next time…

Things to try

• Take a break after any period of concentrated effort. When you return you’re likely to see things with fresh eyes.

• Next time you’re getting from RED to GREEN jot down as many alternative code changes as you can think of. Which one do you choose to move forward with, and why?

• Look for opportunities to increase the symmetry and self-similarity in your code. Does this always help with readability?

As always, why not let your fellow readers know how you get on when you try these…

In part 2 I increased the amount of duplication, so that my tests both told the same story consistently. So currently I have this code:

Let’s review this from the point of view of the 4 Rules: Firstly, these tests are passing. And there is no other code, so by definition everything must be covered by tests (another benefit of TDD As If You Meant It). Second, do these tests clearly tell the story my Customer told me? Honestly, I can’t really tell; they look as if they probably do, but code this verbose is quite hard to review for readability. The noise from that duplication is so loud that I can’t get past it — and so I think I have to fix it before I can do any more.

Speaking of noisy duplication…

The only difference between the two tests is that ‘A’ in the itemsScanned array. That difference should be standing out loud and proud, informing the reader that it is the entire reason for the existence of the second test. But it is currently buried in the mass of code, and so the tests look too similar to be useful. But that ‘A’ is the clue that tells me I need to Extract Method and give it a parameter. I’ll extract into this test file for now, because until I’ve done that I won’t really know what to call it. So:

Commit: Extract checkout function. (I named it checkout for now, because that’s the name of the kata we’re doing.)

The good news here is that these tests are now explicitly coupled: they are clearly testing the same thing, and if it changes they will both test the changed thing. What was previously implicit — our intention that these tests should be coupled — is now explicit, and we can read that in the code locally.

So now it’s back around the 4 Rules. Well, the tests are still passing, so that’s good. But in extracting this function I’ve added a new name (checkout) to our domain model and I’ve changed the nature of itemsScanned from being a constant to being a function parameter. This is the “dynamo” that Joe Rainsberger talks about: every time we fix a Once And Only Once violation we change the set of names we’re using. So rules 2 and 3 go round and round.

All of which means that I must now review the names I’m using and the story they are telling. It would be tempting to start at the top of the source code and read down, looking at the names in turn. But the names are only “good” or “bad” in context; I need to start with the story and adjust the names until they work as a narrative. So I begin at the “outside”, with the tests.

The first thing I notice is that lines 10, 12, and 13 are intended to refer to the same domain concept, but use two different names for it. I think this is another subtle case of implicit coupling: I want the reader to make a connection between the description of the test and its implementation, but that link is currently only implied at best. The description “total price” feels more correct (subjective application of domain knowledge?), so I rename the variable in both tests to match:

Commit: Rename variable to match the domain.

I read these tests again and now I’m not sure that checkout is right. Would scan be a better fit? It’s cheap to find out:

Yes, that feels better: I scan a list of items and get back a total price. Commit: Rename function to tell a clearer story.

Now I notice that totalPrice could be a const. And in fact, as it doesn’t change and is used only once it could be inlined. Do I want to lose the expressive power of having the extra name here? Only one way to find out:

Hmmm. Each test now has three closing brackets together, which definitely makes me slow down when attempting to parse the code. But I have a general distrust of temporary variables (even though this one is a const), so right now I feel quite conflicted. This code now feels more “technical” and thus harder to read; but it has one fewer variable, and that’s something I usually strive for.

If I were to keep this version I feel the name scan now doesn’t help as much as totalPrice used to; I’m inclined to press on without the const, but with the previous vocabulary. How about this:

That definitely reads better (tells the story to my Customer), but those nested brackets are still irksome. Actually, the innermost pair of brackets could be removed from those expressions (lines 12 and 16) if the list of items had a name. But that would introduce another temporary variable, which is something I’m trying to avoid. Unless I look at the two tests together and realise that they are incredibly similar. Could I replace them with a single parameterized test? A quick Google tells me I can do this:

And when this runs, the output looks like this:

I definitely like the test output, and I think line 15 reads better than either test did in the previous version. I still have to pause when reading those arrays on lines 12-13 though, so I wonder whether I can use whitespace to help:

Yes, I think I can tolerate that. It’s really line 15 that is the big attraction of this approach, I suspect because I have extra names (the test parameters) without having extra temporary variables. Commit: Replace the tests with a table of cases.

So now I’m happy that the tests tell their story fairly well, let’s drill down one level of abstraction and look at the function we’re testing:

Two problems strike me here: First, the domain concept of “scanning” isn’t mentioned anywhere else now; and second, there’s a wee bit of friction between the names currentPrice and totalPriceOf. I’m cavalier enough to think that I can fix both of these in one edit:

For once my cockiness pays off. Commit: Change local names to match the domain. And now that my attention isn’t diverted by those names, I see that line 5 looks like overkill. Do I really need a ternary just to add 50 to 0?

That’s better, and I think it tells the story more clearly too. Commit: Clarify the totalling algorithm.

That feels like a lot for today, so it’s time to quickly recap. I began by fixing a violation of the Once And Only Once rule; but I think it’s more important to say that I explicitly coupled the tests to each other, as intended by both the Developer (me) and the Customer (also me).

I then spent quite a few moves on telling the story; and once or twice I found that simplifying the story and/or the names also allowed me to see other duplication or superfluous elements that I had previously missed. Reader Walter Nuccio commented on Runtime and compile time suggesting that we could view the second Rule (expresses intent) in terms of explicit coupling too: The names we use should be explicitly coupled to domain concepts, and the story told by the Customer should be explicitly represented in the code. This is what I’ve tried to do with these naming moves today.

Right now I’m pretty happy with this code, so next time I plan to move along and add the next test. But I will nevertheless begin with a read through the code to check how well it communicates; because currently my perception is heavily influenced by the fact that I just spent a couple of hours right here in this context, and so I’m biased by today’s momentum.

Does all of this feel too slow to you? I think it only seems slow because I’m calling out my thinking as we go along. Try it yourself and let us know how it feels.

Leave a comment

Things to try

• When you’re assessing whether your code tells its story, start at the outside and work inwards only when the outer layers of abstraction communicate extremely well.

• Next time you have to refactor, consciously cycle around the 4 Rules. In particular each time you change anything, start again with a new review of the names and the story they tell.

As always, please share your results by leaving a comment if you try these.

A the end of part 1 we had this code:

It’s now time to REFACTOR, which I consider to be very much the hardest part of TDD. How should we proceed?

Well, first let’s make a list of the problems I can see in this code.

1. Our intention is that these two tests should be testing the same thing. That is, we expect them to be coupled, but they aren’t. There’s nothing preventing me changing the tests independently.

2. The story told by the first test now seems out of date compared to the second, because in the first test there is no mention (in the code) that no items have been scanned.

3. There are zeroes on lines 3, 4, 5, and 9 — they are all the same zero, but the code does nothing to hint at that.

4. There are 50s on lines 8, 11, and 12. Again, these are all the same 50.

I’ve probably missed some places where our intention isn’t expressed explicitly, or where some coupling is not explicit. Did you see any I missed?

Leave a comment

Let’s assume that my list above is reasonably complete. I don’t think it matters if it isn’t, because my perception of the code will change as soon as I make any changes. So we’ll be constantly revisiting and refining our list until we decide it’s time to move on. The important thing now is just to make a start at improving this code. So, where to begin?

At this point I find myself hesitating. Does it matter which order I make these refactorings? If I change A then B, will I get the same code as if I had changed B then A? Is there a “better” choice? If I do A first, will that back me into a corner such that it will later be harder to do B? Is there an “optimal” sequence in which to make these changes?

I do this all the time, and it’s mostly futile. I think it’s a personal hangover from the days before TDD — I still haven’t completely lost the habit of wanting to “solve” the problem before I write any code. What would you tackle first? Make a note before reading any further.

Leave a comment

So, a quick slap on the wrist and I remember to go back to the 4 Rules. My top priority — at least according to my personal reading of the 4 Rules — should be to express intent. There are several ways in which the current code doesn’t do that, and I’m going to pick consistency first. Both tests should be telling the same basic story, with the only differences being that ‘A’ and the corresponding 50. So I want to change both tests so that they tell the same “shape” of story using the same terms.

First, I change the second test so that itemsScanned reflects the plurality of its name:

Now I can change the first test to tell a more similar story:

The tests are green, so I commit: Make the tests more similar shapes.

This feels clearer, but I’m still not happy that our intention is being well expressed. I find my eye repeatedly drawn to line 11, which has no counterpart in the first test. And because of that, I’ve just had an idea; an idea that I really like…

I want to follow the 4 Rules, so I want to change this code to express my intention before I tackle any violations of the Once And Only Once rule. In fact, for the sake of intentionality I’m going to make the duplication worse now. And all because line 11 is an asymmetry between the two tests.

Another way to read line 11 is that it adds 50 to the current price if there’s an ‘A’ in the scanned items list — in fact, if there’s anything at all in that list. So first I rename that price variable to reflect the verbal language I’m using when I discuss the code:

(This is an important step, because it helps to reduce friction and cognitive load. If we’re using one set of vocabulary when discussing the domain, the code shouldn’t be using a different set of vocabulary.)

Next, I tell the story above in code:

I think this test now tells the story we want, and does it reasonably simply. And now I can tell the same story in the first test:

Commit: Tell the same story in both tests.

It’s worth noting that I’m leaning quite heavily here on the fact that the 4 Rules are a set of priority calls. I’ve added unnecessary stuff to the first test (violates the 4th rule) and I have apparently increased the duplication between the two tests (violates the 3rd rule). But because the 2nd rule takes precedence I’m allowed, nay encouraged, to do that. And what’s more, we can now see the implicit coupling between the tests quite clearly, expressed as duplicated code. That duplication was always there, but previously it was hidden somewhat by the different ways those two tests told their stories.

Next time I’ll probably invoke the Once And Only Once rule on these tests. Although it’s often foolish to make predictions…

Things to try

• Make a list of problems you can see in your own code, and prioritise them according to the 4 Rules.

• Make sure the names you use in the code reflect the vocabulary you use when talking about that code.

• Find a place where your code doesn’t tell the story you and your Customer intend; refactor until it does.

As always, if you try these please share your experience with us all by leaving a comment.

So now, like a glutton for punishment, I’m going to do something similar again.

I’m going to tackle Dave Thomas’s Back to the Checkout kata (again). I’m going to show you every step of the way while documenting my thinking as openly and as accurately as I can. I want to explore TDD’s REFACTOR step again, this time from the point of view of the 4 rules of simple design and with a particular focus on making the implicit explicit. And because this will be quite a long series of articles I’ll be chucking them at you twice each week instead of the usual once. (You lucky people.)

And if it goes well — and maybe also if it doesn’t — I’ll probably do it again in a different (kind of) programming language. Because I think an important part of knowing how to refactor is also knowing how language affordances enable or disable the various solution patterns we might consider.

For this first run through I want to use a popular language, and one in which types are not explicitly visible in the source code. In 2015 I used Java, and thus the explicit types helped make some kinds of coupling easier to see and easier to fix. This time I’m going with Javascript, and I hypothesise here and now that I’ll find fewer solution options when attempting to eradicate Connascence of Position, for example (if it arises). No doubt we’ll see.

I’m going to follow Dave Thomas’s lead from the original kata statement and implement my tests strictly in the order he presents them.

So without further ado, here’s my first test:

And when I run it:

(I’m using ES6, and Jest, and make. Because those are the tools I’m comfortable with.)

Some might say that a test that doesn’t compile isn’t a “failing test” in the terms of TDD. I beg to differ, and we’ll explore that topic a little more in a moment.

But first I’m going to commit this: Install toolchain and write first failing test. You can follow along with these commits via the public git repository at https://github.com/kevinrutherford/hc-js-checkout, where you can also look into my Makefile and other details of my toolchain. (For the most part I expect that stuff to not be relevant to the problem we’re exploring here, so I probably won’t mention it again.) Note that due to holiday and work commitments I’m writing these articles in batches a few weeks ahead of publication time; so in the repo you’ll already be able to see where this is going, if you want to look ahead.

Now, what to do about that failing test…

I’m going to adopt Keith Braithwaite’s TDD as if you meant it style. TDDAIYMI has the following, stricter, rules:

1. Write exactly one new test, the smallest test you can that seems to point in the direction of a solution

2. See it fail

3. Make the test from (1) pass by writing the least implementation code you can in the test method. 

4. Refactor to remove duplication, and otherwise as required to improve the design. Be strict about using these moves:

   1. you want a new method—wait until refactoring time, then… create new (non-test) methods by doing one of these, and in no other way:

      1. preferred: do Extract Method on implementation code created as per (3) to create a new method in the test class, or

      2. if you must: move implementation code as per (3) into an existing implementation method

   2. you want a new class—wait until refactoring time, then… create non-test classes to provide a destination for a Move Method and for no other reason

      1. populate implementation classes with methods by doing Move Method, and no other way

Keith doesn’t recommend that we do this in our day job, but in my context here it feels like exactly the right choice. By following these rules I will be forced to refactor my solution into existence, without the aid of any magical starting design that I would then need to justify.

So I change my failing test as per Keith’s rule 3:

And violà:

Commit: Pass the test in TDDAIYMI style.

Does this feel like “cheating”? It’s thought-provoking though, isn’t it? I have a passing test, and yet I’ve done much less “design” than I might usually have done. And hopefully the point of this will become clear after the next couple of tests and refactoring steps.

Speaking of which… Can you see any refactoring that needs to be done? Actually, now you mention it, I’m looking at the test description in the make output and thinking that “back to the checkout has zero price before items are scanned” doesn’t make a lot of sense. I go back to Dave Thomas’s Ruby example and realise I haven’t quite transliterated his intention correctly. So I refactor the test to be this:

Now the test run tells a better story:

I wish this output had less noise, so please drop in a comment if you have Jest tooling that can do that. For now, I can commit: Tell a better story when the test runs.

I think that’s it for refactoring at this stage. So let’s move onto Dave’s next test:

So, this is where TDDAIYMI really kicks us hard. To get this to pass I’m going to have to somehow represent in the test that I scan an “A” and get a price of 50. Well, this is still TDD, so I should be getting this to pass without doing much — if indeed, any — design in my head. How about this:

This feels like it tells the story intended by the test: We begin with a zero total, then we scan an “A” and then the total price becomes 50. (The const itemsScanned is highlighted because vim is helpfully telling me that it isn’t used.)

All tests pass:

So I commit: Get the correct price when scanning an A.

Now it’s time to refactor, and this is the moment when TDDAIYMI pays off. This code now violates the 4 rules — in particular the Once And Only Once rule. Next time we’ll fix that — but in the meantime drop me a comment: what would you refactor now, and why?

Leave a comment

Things to try

Take half an hour to do a (different) kata using the TDDAIYMI style. What did you learn about your usual programming style? Or about how much “design” you do without consciously calling it out?

1. Every occurrence of text such as [[Habitable Code]] is replaced in the rendered page by a hyperlink; when the link is clicked, it opens the wiki page with that title. Fairly standard for a wiki.

2. A wiki page can also contain content that is calculated dynamically, at the time the page is rendered. This occurs whenever the page’s Markdown content includes text of the form [macro: f], where f is one of Incoming, Search, MissingPages, Orphans, RecentChanges and a few others. Incoming is particularly useful for Category pages, for example.

This is the top part of a rendered page:

Everything below the title is rendered by a Hypercard React component. Here’s a CRC card for Hypercard:

And if the reader clicks the page’s title, that Hypercard is replaced by a PageMetadata component, which among other things displays a list of the pages that link to this page:

Here’s a CRC card for PageMetadata:

The problem

We can see that Hypercard and PageMetadata share a responsibility and at least one collaborator.

Here’s the current source code of the PageMetadata component:

But reference to that <Incoming /> component represents knowledge of how a Hypercard renders incoming links. So PageMetadata knows how to insert a list of incoming wiki links into the display, and so does Hypercard; they both use the Incoming React component. PageMetadata has “borrowed” part of the internal implementation of Hypercard.

I find these problems quite difficult to think about, so I made a diagram to help me:

We can see why it’s a problem if we consider what might change and potentially break this code. Hypercard could replace its use of Incoming with something different, having a different display or using a different API endpoint. PageMetadata could do that too. And yet that’s not what my Customer wants. I checked with him (me), and he wants both Hypercard and PageMetadata to calculate and display the incoming links in the same way.

This is a very important observation, and probably the key takeaway from this article: The intended coupling in this code comes directly from the Customer. We have a requirement that these two components display the same set of incoming links, calculated the same way and displayed the same way; and we have a requirement that they continue to evolve together (at least for the foreseeable future). And so there must be a single place in the code that reflects that requirement. The code should say “here’s the one decision that dictates the behaviour of A and B”; whereas the code we have says “currently A and B are independently choosing to use the same helper”.

I get a huge amount of benefit when I can relate coupling directly back to something from the Customer. I wonder:

Is it generally true that things should be coupled in the code if, and only if, the Customer wants them coupled in the application’s behaviour?

Another way to say the same thing: We have explicit coupling, but it is of the implementations, not the intent. The Customer’s intended coupling is missing (or is implicit at best). There is no representation in the code of the coupling we wish we had.

Solution options

We can now see that the problem here is not the coupling per se, but the fact that the coupling we currently have is “accidental”. So how can I change that? How can I guarantee that both Hypercard and PageMetadata use the same Incoming component? And could I write a test for that? I think there is a choice between two general approaches to problems such as this:

1. Arrange for some other code to supply both PageMetadata and Hypercard with the tools to be used for displaying incoming links.

2. Have one thing use the other — in this case, PageMetadata could use Hypercard.

In our case here, option 1 won’t scale. Based on the history of this codebase, it seems quite likely that my Customer will want PageMetadata to evolve and display other stuff. Injecting one common algorithm now feels like a short-term solution; soon I will probably need to inject more and more.

So instead I’m going to adopt the second approach. I rewrite PageMetadata to be this:

By making this change I have clearly and explicitly stated that PageMetadata delegates to Hypercard, and thereby makes use of all of its current and future capabilities.

In connascence terms, I’ve replaced Connascence of Algorithm by Connascence of Name and Type. I don’t find that to be as helpful as saying this:

I’ve represented the Customer’s intention explicitly, once and only once, in a single line of code.

And now that the code looks like this, it seems to me that I don’t need a test. Unless I want to capture the Customer’s requirement, of course. Would you write a test here?

Leave a comment

Root causes

Let’s step back for a moment and look at how this problem came to be in the code.

Obviously the first step would have been for me to ask the Customer how closely the PageMetadata display should be coupled to that of the Hypercard. This is something that software developers rarely do, and yet establishing the intended coupling in the requirements is an important part of the analysis of any user story, and getting it right can avoid huge amounts of future rework. It can be as simple as checking “Should these two domain concepts evolve together?” Of course, such questions weren’t necessary in the days when we perfected our requirements specification at the start of the project, and so I suspect we’ve simply forgotten to add it to our habits now that our software evolves iteratively and incrementally.

But there’s also another contributory factor in this case, and again it’s something I see in a lot of codebases: Hypercard and its helpers were all just sitting around, mixed in with all of the other React components in the same source folder. Even though the helpers are — conceptually and practically — part of the implementation of Hypercard, this was not reflected in the way these components were organised in the codebase. This problem is also evident in the CRC card shown above for Hypercard: those helper components should not be listed as collaborators, because the intention is that they are implementation details.

Again, the intended coupling — this time it’s the developer’s intention — was not represented explicitly in the codebase in any way. And this made it easy for PageMetadata to “reuse” the Incoming component, despite the intention that, logically, Incoming is “part of” the implementation of Hypercard.

In fact, this is how I noticed this problem. I was tired of having to sift through the huge, flat mess of components; I wanted to find groupings and patterns among them. As part of this effort I had decided that Hypercard and its helpers should form a single encapsulation unit and I was moving them all into a new source folder. And that meant I had to change the import statement in PageMetadata, which struck me as odd. And so here we are.

Prevention

So PageMetadata made use of Incoming, but should that even have been possible? The code is obviously not clear enough about the fact that Incoming is “part of” Hypercard, so should Incoming be invisible to any and all other components? And if so, how could I express that in Typescript?

Again, I can think of two options (I’m not a Typescript expert, so please let me know in the comments if I missed something):

1. I could make Hypercard a class component and have the helpers be private members of that class. But Hypercard would then be huge. And private methods aren’t (easily) testable.

2. Or I could create a folder for Hypercard and its helpers, but export only Hypercard from the folder’s index.ts. That doesn’t enforce anything, but as a convention it has merits. The folder represents the encapsulation unit, and the index.ts represents its public interface. I could see at a glance if any source file imported from something like ‘../Hypercard/Incoming’ so that would be a red flag.

In fact I’ve chosen option 2 and it seems to be working so far. It’s an Explicit solution, but only by convention.

Recapping

So to recap, my code had two instances of Implicit Coupling: Firstly, the intention that two rendered components should in future evolve together. And secondly, that certain components were internal to the implementation of another and should not be used outside of that context. (How would you express those in the language of connascence? Or in terms of code smells?)

In both cases I’ve tried to find a way for the code to make that intended coupling Explicit, so that it can be read locally, once and only once in the codebase.

Things to try

1. In your next user story conversation be sure to discuss how the various domain concepts are likely to evolve in relation to each other. Then try to express that intention in your code.

2. If you have a module like Hypercard, that consists of more than one encapsulation unit, find a way to encapsulate the whole lot very obviously in your codebase.

Try fixing similar problems in your code and practices today; and please leave a comment sharing your results.

Subscribe now

1. Outline a single simple example of implicit coupling.

2. Explore solution options in a wide variety of different (types of) programming languages.

This could all go horribly wrong, so please bear with. I have no idea where this might take us. But I haven’t seen this done anywhere else before — not even Martin Fowler has written anything similar, so we’re on our own. I think it’s fairly inevitable that I’ll miss things, so please do chip in when you see something I haven’t thought to consider…

Leave a comment

The example I want to use today is that of a function that takes two parameters of the same type or no type. The caller’s code is coupled to the parameter order, because passing them in the wrong order would mean that the function will probably do something unintended at runtime. The coupling is usually implicit, so how can we arrange the function’s signature so that it is obvious in the caller’s code how the values supplied map to the function’s parameters?

Note that even if the function checks the values it was passed and rejects them — for example by throwing an exception — when they are invalid, that’s a runtime check. It places nothing explicit in the caller’s code to clean up the coupling.

Solution options

Solutions to this problem naturally all involve changing the function signature. It seems to me that we have a few options, depending on what our programming language supports:

1. Change the types of the parameters to be different.

2. Use named parameters.

3. Don’t pass two parameters: group them into a structure.

4. Don’t pass two parameters: split the call into parts.

Let’s look at each of these options in turn…

Parameters of different types

This, of course, is only possible if our code is written in a language that has static typing. But it is also only possible if the parameters represent values taken from two different domain types. For example, in C# we might change

to

In this particular case this has the additional advantage that we’ve addressed some Primitive Obsession, but that won’t always be true.

But the most important aspect of this refactoring is whether we can now see the coupling explicitly in the caller’s code. And we can, because the caller must arrange to have instances of those new types available. So the caller will also change, to something like:

Thus at both ends of the coupling I can see the exactly what might break, without having to run a compiler or tests or the application itself.

However, if our language doesn’t allow for static types we could perhaps offer named parameters…

Named parameters

Some languages such as Ruby, C#, Clojure, Python etc allow the function to state that the caller must provide names when passing parameters.

So for example

This allows the caller to pass the parameters in any order, and again the coupling has been made locally explicit in the caller’s code.

However, if our language doesn’t allow for static types or named parameters we’ll need to change the number of parameters instead.

Over the years I’ve observed that code that is more habitable tends to have very few functions with more than one parameter. So I do generally feel that my preferred option, regardless of the programming language facilities I have available, is to group parameters into a structure or split the call into parts that have only one parameter each.

Pass a structure

If we can’t statically type our parameters, or give them static names — as, for example, in Javascript — we have no option but to avoid having multiple parameters at all. Most languages allow us to group things into larger structures, so we could do this:

As with all of the other options, the caller has to change such that it explicitly names the parameters, and so the Connascence of Position goes away.

I suspect many programmers might object to the additional syntax and dereferencing needed here, saying that the two-parameter version is simpler. But for me, that’s not what “simple” means. In the 4 Rules of Simple Design, brevity is our lowest priority. Here I’m adding syntax in order to make some coupling explicit. So this code tells the story better, and also is kinder to the caller.

Split the call

The major alternative to passing a structure is to split the function into two functions, usually arranged such that the second function is called on something that has the first parameter as internal state. Think of the Builder pattern, which is common in the Java and C# worlds.

In the Customer example I’ve been using in this article I don’t need anything as sophisticated as a Builder, because I can easily (I assume) split this function into two like this:

(Example in Ruby, but would work in any other language similarly.)

But what if there is more of a semantic connection between the two values? We’ll usually need objects or Builders or monads in order to accomplish this. For example suppose I have this Javascript code:

I could consider refactoring like this:

Aficionados of code smells may look at this and cry “Method Chain!”, but note that the methods are received by two different objects of two different classes. In fact there’s a stronger case here for complaining about violation of the “law” of Demeter, because in the refactored code the caller is now coupled to the existence of shelves, and thereby possibly to implementation details of the Warehouse. Yes, I think that’s true in this case — so I would probably have been better taking a different route and introducing an object:

In most cases, where I can find reasonable domain terminology for the intermediate type(s) this approach can significantly improve the code’s ability to tell the customer’s story.

So that’s a very quick tour of some refactoring options for dealing with this one kind of Connascence of Position. I’ve probably missed a lot of possibilities, so please drop them in the comments where you see things I haven’t.

Things to try

• Review your code for functions with more than one parameter and try each of the options above as an alternative design. What forces are at work to encourage you to pick one option over another? Is the cost of the refactoring worth the improvement in habitability?

If you try this, please let us know in the comments. And please also point out those inevitable cases that I’ll likely have missed!

1. Starting with error cases or null cases.

2. Writing tests for invented requirements.

3. Writing a dozen or more lines of code to get to GREEN.

It was a very long post, so I’ve taken the three parts and expanded each into its own article, also incorporating the comments I received in 2014. This is part 3, and will deal with taking a step that’s too big…

When the bar is red and the path to green is long, TDD beginners often soldier on, writing an entire algorithm just to get one test to pass. This is highly risky, and also highly stressful. It is also not TDD.

Let’s look at an example. Suppose you have these tests (Java / JUnit):

And suppose you have been writing the simplest possible thing that works, so your code looks something like this:

Now imagine you picked this as the next test:

This is a huge leap from the current algorithm, as any attempt to code it up will demonstrate. Have a go yourself right now; go ahead, I’ll wait…

I think there are probably two fundamental reasons why the next test might take a lot of work to get passing: Firstly, the test may be genuinely a long way from the current functionality. In this case, maybe it’s worth looking for a smaller slice of the product to tackle.

Or secondly, there is probably a lot of coupling between the code and the existing tests. This is the situation in our example above, and our first priority should be to address that coupling.

So, what did you find when you tried to get the test above to GREEN? The simplest I could do was to write pretty much the whole algorithm. Why? Well, the code duplicates the tests at this point ("happy" occurs as a fixed string in several places), so we probably forgot the REFACTOR step! It is time to remove the duplication before proceeding.

Some TDDers would use the triangulation technique here by writing a new test that fails precisely because of the coupling in the existing code:

YMMV, but personally I find this failing test to be a distraction. I prefer to focus purely on the coupling and let that take my code to a better place. So, without writing any new tests, what should I refactor to fix that coupling?

Everything revolves around those seven instances of “happy”. So looking at this from the point of view of implicit coupling, I note that line 7 in the code will break if the test passes anything other than “happy”. But in that case the happy in my result string should simply be the same as the input text. So I can change the code to be this:

Everything is still GREEN, and we now have only six instances of “happy”.

But the large step we had to take for the “happy monday” test was caused by line 5 in the code, so let’s look at that now. Let’s change it to this:

This passes the tests, but it is still implicitly coupled to the test code because of that 2. That’s simple to fix too:

Now only the tests mention “happy”, so I’m happy too!

Now let’s add back our difficult test:

I can make this pass more easily now:

It ain’t pretty, but it passes the tests. And now I have some obvious coupling to attack, which will help me get closer to a complete working implementation.

I think the key point for me here is that by addressing the coupling during the REFACTOR step we are making the next RED-GREEN cycle easier. Refactoring on GREEN is much less stressful than trying to hack in a big change on RED, so that’s where I want to focus my energy.

One of the reasons this newsletter exists is that I want to explore the effects of addressing implicit coupling. So far, based on very few examples, it seems to me that most of the time (citation needed) converting implicit coupling into explicit coupling also adds some generality to the code. That’s what happened in our example above. And it seems to me that such generality usually helps to make it easier to add the next piece of functionality. Let’s find out together if those ideas hold…

Subscribe now

The step from red bar to green bar should be fast. If it isn't, you're writing code that is unlikely to be 100% tested, and which is prone to errors. Choose tests so that the steps are small, and make sure to refactor ALL of the duplication away before writing the next test, so that you don't have to code around it whilst at the same time trying to get to green.

Things to try

• If you notice that you need to write or change more than 3-4 lines of code while your tests are RED, stop! Revert back to GREEN. Now either refactor your code in the light of what just happened, so as to make that test easier to pass, or pick a different test that is closer to your current behaviour.

• Review your existing tests — how coupled are they to your code?

1. Starting with error cases or null cases.

2. Writing tests for invented requirements.

3. Writing a dozen or more lines of code to get to GREEN.

It was a very long post, so I’ve taken the three parts and expanded each into its own article, also incorporating the comments I received in 2014. This is part 2, and will deal with writing tests for invented requirements…

Imagine you and I have to test-drive the design of an object that can count the number of occurrences of each word in a string. We’re doing TDD, but we have no code to test; we have nothing to hang our first test on, so we need to invent something, fast!

Luckily, our pre-test thinking tells us that our solution will decompose into certain pieces that do certain things, and so we begin by testing one of those and building upwards from there. For example, in the case of the word counter we may reason along the following lines:

YOU: "We know we'll need to split the string into words”

ME: “So we’ll need a method that can do the splitting”

YOU: “Great. How shall we test it?”

ME: “The simplest thing would be to count the words after the split?”

And so we write this as our first test:

What’s wrong with this? Well, no-one asked us to write a method that counts the words, so we're wasting the Customer's time. We might be able to ship real business value to our users sooner if we did something else instead.

Equally bad, we've invented new scope: a new requirement on our object's API, and locked it in place with a regression test. If this test breaks at some time in the future, how will someone looking at this code in a few months' time cope with that? A test is failing, but how do they know that it's only a “scaffolding” test, and should have been deleted long ago?

Working this way means that we often end up with code in which it’s difficult to tell what is necessary — ie. requested by our Customer — and what was invented purely for the sake of following the TDD mantra.

Sometimes it can be pragmatic to write “scaffolding” tests such as this, perhaps as a discovery exercise to get an idea of how it feels to work with a particular design. And if we do, it’s important to remember to go back and delete them as soon as possible.

Because even if this test never fails, its very existence makes it appear that countWords is a requirement. We’ll need to spend some time checking with someone before we can change this API or delete it.

So start at the outside, by writing tests for things that your code’s consumer (eg. the end user) actually asked for.

Next time: taking a slice that’s too big.

Things to try

• Look around your codebase for tests like this. Delete as many as you can.

• Next time you have to TDD something that doesn’t exist yet, start with a thin slice of genuine business value, and do as little design as you can. No, less than that!

Leave a comment

Each time I visit a team that is relatively new to TDD I find the same basic mistakes cropping up every time. The three mistakes I see most often are:

1. Starting with error cases or null cases.

2. Writing tests for invented requirements.

3. Writing a dozen or more lines of code to get to GREEN.

This article will deal with the first of these...

Imagine you have to test-drive the design of an object that can count the number of occurrences of each word in a string. I will often see someone who is new to TDD start with tests such as these (example in Java/JUnit):

Tests like this are counter-productive for a number of reasons:

1. They feel easy to write, and give a definite feeling of progress. But that is all they give: a feeling of progress. These tests really only prove to ourselves that we can write a test. When written first like this, they don't deliver any business value.

2. These tests don’t get us closer to validating the Customer1's assumptions. Time spent writing them hasn’t allowed us to demo anything or ask for feedback. There is no business benefit and no learning benefit.

3. These edge-case tests increase the code’s cost of ownership; by putting this code into the codebase too early I find it just gets in the way. Chances are we’ll have to tiptoe around them while we build the actual business value, and that will slow us down even more.

It is usually much better to begin by building a simple thin slice of positive business value (some folks call this a “happy path”, to remind themselves that no error cases have been dealt with yet). And when we’re successfully delivering some business value, that is the time for us to remind our Customer that we have some edge cases to consider.

So start with tests that represent business value and allow a thin, usable slice of the product to be built quickly. For example:

This way you will get two major benefits:

Firstly, you can ask the Customer that vital question (“Is this what you meant?”) sooner, and they will invest less before they know whether they want to proceed. So the biggest payoff of leaving the edge cases until later is that they actually allow the Customer, should they decide to do so, to ship working code that provides benefit. Sure it may have limited robustness, but that risk can be worth more than waiting until you have finished polishing every edge case that can be thought of.

And secondly, you will likely have a simpler development job to do, both while developing the happy path and later when you come to add the edge cases. Because very often it will turn out to be much easier to add edge cases to an existing solution, after the happy path is done. In fact some of the edge cases may now already be dealt with "for free", as it were, simply by the natural shape of the algorithm we test drove. Others may be easy to implement by adding a Decorator or introducing a guard clause.

Now, you might object to me calling this a mistake, because tests such as those above allow us to define a class API without having to worry about the implementation. There are a number of design decisions that have been made as a result of writing some very quick tests, e.g. the name of the class (WordCounter), the name of the method that does the counting (count), whether the parameters are on the count method or the class constructor, etc. But I don’t see those as a benefit; to my mind they create risk because they haven't been checked in realistic scenarios. I would prefer to make those design decisions in code that is delivering business benefit so that, ultimately, they are required to support real users. In short, I want a correct algorithm first, followed by habitable code.

Things to try

• Next time you have to write the first test for something new, try to deliver positive business value from the happy path.

• Review your existing edge-case and error-case logic: how much of it could be pushed out of your domain code and into decorators or CHECKS?

Next time, another TDD rookie mistake…

Daft question, I hope you’ll agree.

But I think I do have a favourite. It’s Shotgun Surgery. Why? Because it tells me so much about my design. Let me explain…

Firstly, many of the other code smells often feel quite ambiguous to me. Is this Feature Envy or is it a reasonable separation of responsibilities? Is this Primitive Obsession or simple value passing between close collaborators deep inside an encapsulated mechanism? Very often I spend too much energy debating questions like this, instead of making progress towards more habitable code.

But Shotgun Surgery is different. It says “You just added feature X and you had to change code at A, B and C”. This means that A, B, and C were coupled — and are now coupled even more.

Note the use of the past tense there. I don’t want to look for or fix Shotgun Surgery until the feature1 increment is done. I want to wait so that I can see all of the damage I’m going to do, because that tells me the most about what the design problem was.

Shotgun Surgery says “You ought to refactor so that you could have implemented that feature increment with a 1-line change to existing code”.

So here’s the process:

1. Add a complete feature increment.

2. Step back and review all of the places in the code that had to change. There was implicit coupling between all of those places, because they all made some assumptions that had to be busted in light of our new feature.

3. Construct a design that would have allowed the feature to be added by instead changing only one place in the code.

4. Refactor to that design.

Why would I want to do this? Because when I’m done, my code will now have a new “seam” — a new place at which extensions such as this can be inserted without changing too much.

Imagine that my code currently has the following design:

Without too much fuss I implement my feature increment. And now I have this (changes in red):

What if, instead, I had first refactored my design to make room for the new feature:

So that I can now implement my feature with little or no change to existing code (new feature in green):

Of course, I’m not claiming that any of this is easy, but I do think it’s valuable. That’s because fixing the Shotgun Surgery in this way prepares the codebase for the future in a number of ways:

1. The code for this whole feature is now collected together in one place, and likely has a name. That’s got to be good for our ability to comprehend the code: It is now obvious where to look for anything related to this feature.

2. The fact that we were asked to add this feature to an existing, working application suggests that similar changes will be asked for in the future [citation needed]. By taking this “open-closed” approach we have likely made the code more amenable to adding alternative options along the same axis.

3. Even if nothing similar crops up again in the future, by making this change we have ensured that the rest of the codebase isn’t infected with knowledge of this feature. So the rest of the codebase is cleaner and not burdened with this responsibility.

4. Deleting this feature will be really easy, if it comes to that.

5. There’s likely little or no implicit coupling related to this feature now. So there will be fewer surprises if it evolves.

6. The part of the codebase that had to be modified to accommodate this feature is now a more stable abstraction, parameterised by the new feature and its alternatives. And the more we do this, the more generalised and stable the core of our codebase will become. This is expected to be good for the long term extensibility.

It seems to me that the benefits to the code of fixing Shotgun Surgery like this are huge and long-lived. But there are also benefits in terms of our mindset: making this change will influence how we make future changes, and how we structure our design to support future change.

Feels like I should write up a worked example someday…

Things to try

• Have a go at Matteo Vaccari’s OCP Kata, which was the inspiration for many of the above ideas. This kata tells you to refactor in this way every time you have a failing test.

• When you finish your next feature increment, do the design exercise above: work out a design in which all of the feature’s code could have been added in one place.

• If you have time, actually change the code to that design.

• Try do the kata on a “real” production codebase, refactoring on RED so that you can make the next test pass without changing code. Which works best for you, bigger steps or smaller steps?

As always, please leave a comment if you try this exercise. Does the codebase feel substantively different afterwards? Could you have implemented the feature like this in the first place? Will you do anything differently for your next feature?

Leave a comment

Subscribe now

This week I thought I’d take a somewhat more detailed look into the 4 Rules of Simple Design. I’ve mentioned them quite a few times in my early articles, so let’s look a little more closely.

To recap the 4 rules, code that is “simple” (ie. habitable) must satisfy the following criteria:

1. Passes all its tests

2. Expresses our intention

3. Says everything once and only once

4. Has nothing superfluous

The first thing to note is that many people list rules 2 and 3 in the opposite order than I have. I actually don’t think there’s a difference — I’d say that rules 2 and 3, in practical terms, feed off each other so much that they may as well be parts of a single rule. I’ll come back to this point a bit later, but first I want to talk about what the ordering of the rules means.

In an ideal world, all of our code would satisfy all four rules simultaneously. In which case their order doesn’t matter.

The order of the rules comes into play when we have code that doesn’t already satisfy them — code that, by this definition at least, isn’t habitable. In this case, the order of the four rules tells us how to behave.

First, they say, get the code working and tested. Nothing else matters. If the code doesn’t work, nobody cares how habitable it is; the other rules don’t come into focus. (Actually, in practical terms that’s not quite true. If the code used to satisfy the 4 rules, and then we broke a test, that code will likely be much easier to fix than if we have a broken test of code that is a tangled mess of unreadable, duplicated logic.) Nevertheless, regardless of the prior state of the code, the 4 rules say that our first priority is the get the code working and tested again. And we’re allowed to break the other rules, if necessary, in order to get back to working and tested.

This mirrors the rules of test-driven development: After the RED step we have a failing test, so we want the GREEN step to be completed quickly. In getting back to GREEN we’re actively encouraged to Do The Simplest Thing That Could Possibly Work. Don’t spend time thinking about code quality or readability; don’t worry about introducing duplication or coupling; and don’t worry about leaving unused code in your wake. Just do what you have to do in order to get that test passing again.

It’s worth mentioning that it’s no accident that test-driven development’s RED-GREEN-REFACTOR cycle starts the same way as the 4 rules of simple design. That’s because they are the same rules. It’s just that the 4 rules give us a more helpful guide as to how to direct our refactoring effort. Which brings us neatly to rules 2, 3, and 4.

After our code is working and tested, TDD tells us to “refactor”, but stops there, before telling us how to go about it. And this is where rules 2, 3, and 4 step in.

First, make the code understandable by anyone who understands the domain. And if you need to introduce duplication in order to do that, that’s fine. The 4 rules say “make it readable first”; then fix the duplication; and only then shoot for minimalism. But you’re not allowed to remove duplication if doing so would make the code unreadable. And you’re not allowed to minimise the code if that would render it unreadable or introduce duplication.

So what do “readable” and “understandable” mean? We want to have the code express the Product Owner’s and the developer’s intentions. In all of the programming languages I can think of, the only tools we have for expressing ideas are the names we give to things. So we need to ensure that every code construct that we create has a meaningful, domain-related name. But we also need to ensure that we choose the “right” things to make nameable. As we break down our algorithm into functions, parameters, variables, classes, modules etc it’s important that those entities map onto the domain, so that the story told by the code makes sense in terms of the major concepts of that domain. I want my code to “tell the story” that my Product Owner told me when explaining their intention for this feature.

Next, on to rule 3. Once we have working tested code that tells the Product Owner’s story, we should ensure that every idea in that story is represented in the code exactly once and no more. And my working hypothesis — the question I’m exploring through these articles — is that this is best accomplished by looking for implicit coupling and making it explicit. My mission here is to see if we can develop a clearer sense of how to apply the Once And Only Once rule in practical day-to-day programming.

As I mentioned above, many (perhaps most) authors prioritise rules 2 and 3 the opposite way around from my list here. The reason I prefer to fix expressiveness first is that I’ve seen huge amounts of unreadable code produced in the name of removing duplication. And since we read each line of code much more often than we change it, I think there’s quite a productivity payoff in having expressiveness prioritised more highly than duplication.

And in practice rules 2 and 3 usually play off each other. Most of the time when we remove some duplication, that activity involves introducing one or more new nameable components into the code. So we have to go back around to rule 2 to ensure that the new names — and the new nameable things — tell the story at least as well as before. So rules 2 and 3 form what Joe Rainsberger has called a “dynamo”; they feed off each other and influence each other. And so it may be that their order doesn’t really matter if we’re being thorough. Be that as it may, I’m sticking with the order above; I want to ensure that if, say, I run out of time, my code a readable first and foremost.

Finally, there’s the fourth rule: be a minimalist. If something becomes unused while you’re following the other rules, just delete it. If there’s a simpler way of achieving something, do it that way — but make sure the code still tells the story at least as well as before.

So, that’s a whistle-stop tour of the 4 rules of simple design, including a little insight into where I think this newsletter fits in the grand scheme of things. Following these rules keeps your code habitable, and therefore also keeps the cost of change lower. But they aren’t easy — and rule 2 in particular is somewhat subjective. Expressing intention is hard!

Things to try

1. Can you completely let go of your “sense of smell” when you’re writing the code to get that test to pass?

2. Can your Product Owner read and understand your code?

3. In particular, if your Product Owner can’t read and understand your tests, you’re not done refactoring.

Please leave a comment if you just tried this approach for the first time: How did it feel? Did it make a difference to your code? What happened when a non-developer read your test code?

Leave a comment

TL;DR:
Don't guess the size of a user story;
slice the story until it’s the size you want.

So there's this big discussion going on about #NoEstimates — and how estimating is wasteful, misleading etc — for what seems like forever. But there are very few published practical alternatives. So what to do if you want to do less estimating? Honestly, I think that's the wrong question to be asking. A more important question, at least for every team I've encountered, is "how can we become more predictable in what we will promise and deliver?" Estimates only go so far in answering this question because, well, they're just guesses. It doesn't matter whether they are expressed as hours, pair-hours, story points, complexity points, Gummi bears or whatever; someone somewhere will attempt to do arithmetic with your estimates and thus turn them into "facts". So estimating is hard, and it's guesswork; it is not my intention here to grumble on about all the side-effects of that — you can read all of that stuff elsewhere. Instead, let's cut to the chase and do something about it.

Estimates are risky and difficult. So let's try the opposite. Instead of estimating the next story, let's play to our strengths as developers and give ourselves a technical and analytical puzzle: Let's fit the story to the estimate. Here's how it works…

When the team picks up the next story, apply the "five-day challenge". First ask, "can we deliver this in 5 days?" If the answer is "yes", just do it and then pick up the next story. But if the answer is "no", have the whole team identify some core nugget of useful value within the story such that everyone agrees:

1. it could be delivered in five days or less, and

2. it will be a useful and valuable product increment.

Deliver that core nugget to your users, then go and pick the next story.

(Historical note: This challenge is very similar to the approach used by Tom Gilb in his EVO method, in which the team is asked to look for the one thing that can be delivered next week that can make a difference.)

This challenge process is fun, and it is exactly the kind of problem many developers and product owners are good at solving. That's a win. Furthermore, there is plenty of good literature out there to help you do it and get good at doing it. Here are three great articles that can help with that:

1. Three Steps to a Useful Minimal Feature by Joe Rainsberger

2. How You’ll Probably Learn to Split Features, also by Joe Rainsberger

3. Guide to Splitting User Stories by Humanizing Work

Shortly after you have split the story to fit into five days, the Product Owner should take each of the edge cases you peeled off, turn them into stories and push them back down the queue. One or two of them may be the next stories to be scheduled, while others may wind up never being picked. All that matters right now is that they aren't essential to delivering the current story, and thus need occupy no more developer time this week.

Of course, if your stories are already small, instead of 5 days pick 3, or 2, or 1. I like 5 days as a starting point because for many teams it's an improvement over their current practice, and it almost always gives time to deliver an interesting chunk of value. The important thing is to pick a number of days and stick to it until you are confident that you have that size of story nailed. Then try reducing it by one day and learn how to slice your stories even more thinly.

When you have delivered the story, record the actual number of days it took. If that differs from five days, take 5 minutes as a team and list the reasons for that variance. Use this to help you do a better job of fitting the next story to 5 days (or less). You’re aiming for stable and predictable first, then for gradually smaller timeboxes.

Note that the 5-day challenge is NOT a challenge to the team, it's a challenge to the story. You all sat down together and dug out a core nugget of useful value, so now go ahead and deliver that without taking any short cuts. If you find yourselves running later than 5 days, don't try to squeeze the story into your estimate. It doesn't matter if the story ends up taking 11 days or just 2. The important thing is to do the story well, and then learn from the actual time it took.

Why have I posted this article in a series about Habitable Code? Because the habitability or otherwise of our code represents the biggest hurdle to slicing our stories thinner and thinner. Back in 2014 Matteo Vaccari wrote this comment on my original blog post:

This is not just a challenge to the user story; it's a challenge to our codebase. Why does it take 5 days to implement this request? Shouldn't we be able to implement this by a reconfiguration of our existing objects? Why is our codebase not closed with respect to this kind of variation? This is a challenge to our process and to the way we program.

I made a similar point in Don’t Forget the Developers: ultimately the habitability of our code is what will determine whether our “agile adoption” has any chance of succeeding.

In practice, this technique dovetails very well with the whole ecosystem of the eXtreme Programming (XP) practices. And it fits best of all with the other team micro-habits that I have evolved through my coaching practice over the last ten years or so. I may write about some of those here too. Or you could hire me to help your team implement XP, and find the best fit for the XP principles and practices in your organisation 🙂.

Here's a video of me explaining the 5-day challenge in a lightning talk at the Scottish Ruby Conference in 2014 (you need to skip forward to 07:54 because Substack doesn’t allow me to set the start time):

Things to try:

Next time you have to estimate a user story, try the 5-day challenge instead. (If your stories already typically take less than 5 days, try the challenge but with a smaller timebox.) Let us know in the comments what happened, what your team and Product Owner learned, and how you plan to take this idea forwards.

Leave a comment

And when you get really good and this, and your team can reliably and predictably deliver value every day, try forgetting about user stories and slice the customer’s problem instead?

I want to grow this newsletter so that it becomes more and more useful to you, so I’d like to get your help in shaping the content.

I know that you, like me, are passionate about the internal quality of the software you create. And like me you’re frustrated that there’s very little practical advice out there to help with refactoring, and with test-driven development in general.

So how can I help? What do we, as a community, need this newsletter to provide?

I’ll put my own goals in the comments, and I’m looking forward to hearing from you too — what can I write about that will help you?

Subscribe now

One final thing: Please also help to make this thread as useful as possible by sharing this post widely among people who share our need for better refactoring advice.

Thanks for your continuing support!

Share Habitable Code

In response to Thinking about APIs reader Richard made this comment directly to me via email:

Have you thought about integration tests? That could solve some of the issues about the changing contracts.

Yes, integration tests — indeed all kinds of automated checking — definitely help to establish our software’s correctness. They operate within the first of the 4 rules of Simple Design: “passes all of the tests”. But the thesis of this series of articles is that we can do more.

Shigeo Shingo, one of the founding fathers of Lean Manufacturing, said something to the effect that:

Inspection to prevent defects is absolutely required of any process,
but inspection to find defects is waste.

Paraphrasing this into the domain of software development:

It is more efficient to prevent defects from entering our code than it is to find them later — even if “later” is only the time it takes to run our tests.

So I want to find ways to bring that feedback forward in time, so that I can “see” the coupling before I break something — and without having to execute anything. I don’t want to have to rely on test execution, or compilation, or static analysis, or any of the other tools provided within a modern IDE or CI/CD pipeline. I just want to be able to look at this one module right here, at this current level of abstraction, and “know” that it is coupled to something else “over there”.

I want to explore whether it is possible to write code that speaks clearly and immediately, regardless of what tools I have at my disposal. And even if you have different tools — less capable IDE, differently configured pipeline, etc — the code should still speak to you in exactly the same way that it speaks to me.

It may be that we will discover that there are “degrees of explicitness”, and that they are somehow related to the speed of our feedback loops. I sincerely hope that isn’t the case though. I have this naive expectation that code quality shouldn’t be related to tooling; that we can discover something “universal” — although I definitely expect those universal ideas to have widely differing expressions depending on our programming language / paradigm / ecosystem.

One final observation: The tests are also code. They are thus built using coupling, both internal — within the tests’ codebase — and with the system under test. Thus, far from “solving” our implicitness problem, I view tests as just another codebase whose coupling I need to make explicit. The code of the tests should still satisfy the 4 rules of simple design, just as our production code should.

What do you think — am I on a mad Quixotic quest? Can we always write code that has no implicit coupling across encapsulation boundaries?

Leave a comment

I think maybe it’s time we began to explore some more (a lot more) worked examples…

Is it safe to say the static section in your "handy cut out" is explicit coupling and the dynamic section is implicit ?

By “handy cut out” Ross is referring to my 2016 representation of the various kinds of Connascence:

These nine kinds of Connascence were identified by Meilir Page-Jones in his book Fundamentals of Object-oriented Design in UML, and I discussed Connascence at length in the article What Happened to Connascence?

Page-Jones suggests that the first five kinds of Connascence can be discovered through static analysis of the code, whereas the last four can only be discovered at runtime. Ross is thus asking whether the boundary between Explicit and Implicit Coupling lies at the same point as Page-Jones’s boundary between the static and dynamic kinds of connascence.

In response, the first thing I would note is that static analysis often requires an omniscient view of the codebase, whereas in these articles I want to steer the notion of Explicit Coupling towards always being local1. My working hypothesis is that the correspondence suggested by Ross doesn’t hold. But right now we’ve explored only a couple of code samples, and so I’m not prepared to make a commitment either way just yet. I believe we’ll need to explore many, many more examples of coupling before we can hypothesise that every example of Connascence of Algorithm, for example, can be viewed as Explicit Coupling.

Secondly, and as I wrote in What happened to Connascence?, it is by no means clear to me that every specific example of coupling can be assigned to exactly one kind of connascence. I believe that connascence is a great “starter kit” for helping to find coupling that might otherwise be difficult to see; but I don’t find connascence to be useful beyond that point. We’ve found some coupling — great, now let’s stop worrying about how we found it and instead focus on improving the habitability of our code.

To sum up, to my mind connascence and implicit vs explicit coupling are addressing different problems:

• The Connascence catalogue can help us find coupling;

• Implicit Coupling is how we decide whether we need to fix it; and

• Explicit Coupling is about how we want the code to look after we’ve fixed it.

Of course, that’s (probably) a gross simplification. But I’ve confused huge numbers of people in the past by talking about Connascence as if it solves all of our problems on its own, so maybe a simplification is just what we need right now…

Please do keep sending me your questions, because by answering them I’m exploring my topic from your perspective. That’s really helping me to see past the things I’ve already skipped past or taken for granted, so thank you!

Leave a comment

You can leave a question by commenting on any of these articles (button above 🙂), or by replying to your subscription email (you are subscribed, right?), or by messaging me via any of these means:

• Email: kevin@rutherford-software.com

• LinkedIn: https://www.linkedin.com/in/kevinrutherford/

• Twitter: @kevinrutherford

Next up, I plan to answer to Richard’s question about API coupling…

Have you thought about integration tests? That could solve some of the issues about the changing contracts

Subscribe now