A Twitter conversation about Primitive Obsession caught my eye today. That conversation began with this tweet:

Re. “primitive obsession,” I say this poker-scoring program wouldn’t be bettered avoiding integers for rank and suit. jsoftware.com/jwiki/TracyHar…

— Tracy Harms (@kaleidic) March 3, 2013

I can’t read J, so I can’t decide much about the quality of the code Tracy wrote, but I do notice one thing:

There aren’t many functions that operate on the primitive data (card rank, card suit, hand classification), they’re close by each other, and they’re all quite short.

Regarding this one example, then, Primitive Obsession doesn’t pose much of a problem yet. Using primitives to represent values with special constraints can lead to low cohesion and high duplication. The low cohesion consists of scattering related ideas throughout the code base, where programmers have a hard time finding them. Such scattering can lead to duplicating special processing logic, and worse, duplicating it inaccurately. That leads to mistakes. This makes me ask a question:

When does Primitive Obsession not smell?

I suppose it doesn’t smell when we use other means to keep cohesion high and duplication low. We can use primitives safely when we keep the special processing logic for those primitive values close together and use willpower (effectively) to avoid duplicating it.

I still can’t account for Tracy’s observation that Primitive Obsession doesn’t figure prominently in array programming, where it ought to run rampant and create serious problems. Some guesses:

• Teams of programmers working in these languages don’t create large, low-cohesion systems, like they do in Java/C#/C++.
• Teams of programmers working in these languages name things better in general, and so create fewer opportunities for misunderstanding.
• Teams of programmers working in these languages work together more closely in general, and so smooth over their misunderstandings more easily and more promptly.

Any ideas?

References

Martin Fowler, Refactoring: Improving the Design of Existing Code. This book introduced me to Primitive Obsession as a code smell.

Ward Cunningham, “The CHECKS Pattern Language of Information Integrity”. This article includes a section on Whole Value, which counters the effects of Primitive Obsession. Whole Values should become attractive code when you introduce them into a system.

James Shore, “Primitive Obsession”. I recommend this article to my students to learn more about Primitive Obsession.

Corey Haines and J. B. Rainsberger, “Primitive Obsession”. Corey and I discussed Primitive Obsession while in Bucharest in early 2010. This article includes a 14-minute video of the two of us chatting about the topic.

Code Retreat. We very commonly use the “no primitives” constraint at Code Retreat to encourage programmers to practise introducing Whole Values very early. I don’t always design this way, but I believe that programmers should understand more deeply the differences between design with and without promitives, so I encourage them to practise.

The bottom line:

Modularity. Details. Pick one.

I routinely work with programmers who feel uncomfortable with tiny methods and tiny classes, in spite of all the benefits of tiny methods and tiny classes:

• easier to test
• easier to read
• easier to understand
• easier to build correctly
• easier to compose into working systems

The programmers who don’t like them cite these problems most often:

• “I can’t find stuff!”
• “I have to click too much to see what’s happening!”

This article by Kevin Rutherford reminded me of this issue. While Kevin extols the virtues of tiny methods, he doesn’t address this phenomenon, although he admits to running into it himself. I wanted to share what I do with him, but it doesn’t fit well into a comment. When I hear programmers complain about these things, I offer the following two responses to them.

You appear to be navigating. Would you like help with that?

I have paired, albeit mostly briefly, with hundreds of programmers by now. Most of them, to my surprise, navigate their code bases to find things. By this, I mean that they open up folders in a navigator view in their IDE, or navigate the file system, in order to locate a file containing the code that they want to read or change. Not wanting to make pair programming suck, I hold my tongue until I’ve built up more trust with the person. If I think they trust me, then I stop them and suggest:

Don’t navigate when you can search.

I just don’t care where to find things any more. Just knowing that “they’re somewhere in this room”¹ suffices. Only when searching fails do I resort to navigating.

The classic book The Pragmatic Programmer teaches us to learn one editor well, which I try to do. As part of classroom training and mentoring hundreds of programmers, I find myself working in unfamiliar environments quite often. When I work in a new one, I spend some time learning how to search for things. In Eclipse, I use “Open Type” and “Open Resource” extensively. Before I knew anything useful about vim, I knew to press / to find text in a file. Before I knew anything useful about Unix, I could clumsily use grep, and more recently I’ve learned about ack and even ag. I don’t use Emacs any more, but I love its incremental search feature. I see this as an extension of the maxim that humans ought to delegate mechanical tasks to the computer, such as searching text for a pattern.

I still see programmers scan web pages with their eyes to find text, rather than use the “search” feature of their browser. I just don’t understand why they do this. I prefer to work in environments where I don’t even know that it stores my code in files!²

This brings me to my other response.

Modularity. Details. Pick One.

If you ask programmers whether they want modularity, they usually claim that they do. It sounds like something they ought to want, books on design tell them to want it, and so I imagine that some programmers claim to want it in order to look good among their peers. Unfortunately, many such programmers don’t appear to understand that modularity comes from abstraction, and that abstraction literally means hiding details, and that doesn’t mesh with their clinging to details. To them, I suggest repeating a little mantra all day today:

I don’t care. I don’t need to know. I don’t want to know.

Giving up details won’t lead you directly to writing modular code, but clinging to details will keep you from it. The more your code knows about its neighbors, the less you can change or replace those neighbors. Changes ripple out to the rest of the system. When you do this, you’re writing more legacy code.

Modularity needs abstraction. Abstraction means hiding details. If you cling to details, then you won’t create abstractions, and you won’t achieve modularity. Modularity begins with your refusal to let others burden you with unnecessary detail.

I noticed that my designs improved once I began stubbornly refusing to know any more than I needed to achieve my current goal. Try starting there. “I don’t care. I don’t need to know. I don’t want to know.”

Look at the SOLID principles and how they relate to not wanting to know details.

• Single Responsibility: I don’t want to know about any other behavior in this system right now.
• Open/Closed: I don’t want to know how things work in order to extend them.
• Liskov Substitution: I don’t want to know which implementation of each interface this code uses.
• Interface Segregation: I don’t want to know anything more than the minimum I need to do my job.
• Dependency Inversion: I don’t want to know how the rest of the system uses me.

I don’t think I can make it any plainer than that.

Of course, I’ve assumed in this article that we want modular systems. You might not. I don’t want to argue the merits of modularity here. Instead, I want to make one thing clear:

Modularity and obsession with details exclude one another. If you want one, then you can’t have the other, so pick one.

Another “demystifying” article. Great! I know… bear with me.

Of the SOLID principles, the Dependency Inversion Principle remains somewhat misunderstood. I’d like to help with that. I hope you’ll ask questions and challenge these ideas, so that I can improve this little article.

I learned the Dependency Inversion Principle from Bob Martin’s article, the salient part of which states:

High level modules should not depend upon low level modules. Both should depend upon abstractions.

or

Abstractions should not depend upon details. Details should depend upon abstractions.

I’ve noticed that I spend the vast majority of my time introducing abstractions and inverting dependencies (abstractions that use concrete things) when rescuing legacy code or adding behavior to legacy systems. Sometimes I feel like I don’t know any other useful trick than invert this dependency. One could make a drinking game out of it.

Even so, not enough people understand and apply DIP. Perhaps if I share a few examples or equivalent formulations, they will.

Move Specificity Towards the Tests

Moving details from production code towards tests clarifies the tests. In particular, I find it easier to relate the inputs to the expected outputs. It eliminates duplication between tests and production code. It highlights opportunities for abstraction and reuse. Corey Haines interviewed me about this in summer 2009.

JB Rainsberger - Move Specificity Towards the Tests from Corey Haines on Vimeo.

(If you can’t watch the embedded video, then click here.)

Move Implementation Choices Up the Call Stack

Dependency injection confuses and annoys people, partly because some people miss the point. Injecting a dependency makes testing easier, by letting us substitute implementations in our tests that make those tests easier to write and understand. Don’t stop there. When in doubt, push new up the call stack. In particular, don’t instantiate a service if you can get your caller to do that. Keep pushing, even more than you think you should. Let all the choices of implementation of each service interface bubble up the call stack until they collect in your application’s or component’s entry point. This shines a huge floodlight on otherwise obscure duplication. It also paves the way for sane use of a dependency injection container, even though you don’t need a container to inject dependencies well. This movement of new up the call stack leaves in its wake a loosely-coupled network of abstractions talking to each other over well-defined interfaces with well-understood contracts. Using this technique helps me remove duplication, which decreases errors, particularly of the “I forgot to change that one” type. Using this technique also encourages me to write code that depends on narrower interfaces, which slowly become more generic interfaces, which makes the code depend less on its context and more suitable to use in other contexts.

Abstraction in Code; Details in Metadata

I first learned this principle from the book The Pragmatic Programmer. You’ll find it as “tip 38”. I encourage you to buy the book and the read the tip yourself. The authors state among the benefits:

• a more robust program
• a more flexible program
• opportunity to reuse the “engine” with different metadata
• opportunity to express metadata in the language of the domain
• opportunity to customise code without rebuilding it

Who could argue with all that?

Quick Summary

If you agree with the specific principles I’ve cited here, then you also agree with the Dependency Inversion Principle. Said differently:

Push details up towards the client and push generic patterns down towards the server.

This principle, applied everywhere, makes testing easier, promotes reuse, both of which reduce the incidence of errors and the cost of development.

So tell me:

• If you already felt you understood the DIP well, how faithfully did I represent it here?
• If you didn’t quite understand the DIP well before, how much has this article helped or hindered your understanding?
• If you explain the DIP to others, how do you do it?
• If you still think the DIP is a load of nonsense, how do you justify that? I’d like the chance to help you as well as fix holes in my own understanding and reasoning.

One More Thing

If you hate Spring’s dependency injection container, then I know why: you have code that depends on the container.

Don’t do that.

Dependency injection is related to the Inversion of Control principle, also known as the Hollywood Principle:

Don’t call us; we’ll call you.

Spring’s dependency injection container calls you; you never call it. Never.

Fine: you call it only from a smoke test that verifies that you’ve wired up your dependencies correctly, but you never call your dependency injection container from production code.

I apologise for the pompous title; I wrote it just for fun. If this “demystifies” anything, I’ll consider that a coincidence.

Of the SOLID principles, the most pompous-sounding is the one named for a person: Barbara Liskov. I don’t label her pompous – I never knew her – but of those five principles, only LSP has a common formulation that looks like the kind of mathematics so many programmers like to avoid, while others flock to.

Let q(x) be a property provable about objects x of type T. Then q(y) should be provable for objects y of type S where S is a subtype of T.

Or, if you prefer:

Subtypes must not change any supertype’s significant behavior. Here, “significant behavior” means behavior upon which clients of those objects expressly depend.

If you like the language of contracts, then you might prefer this formulation:

Subtypes must respect the contracts of their supertypes.

If, like me, you like to check contract compliance with contract tests, then you might prefer this formulation:

Subtypes must pass the same set of contract tests that their supertypes pass.

Remember that subtype here means any implementation of an interface or subclass of a class.

So, what does it look like when we violate the Liskov Substitution Principle? Usually like this:

1

// This should never happen

You can’t trace all such problems to a violation of LSP. Sometimes you have a simpler disagreement between a client and its collaborator. Even so, subtyping without careful attention to the type’s contract opens the door wide to breaking the contract, which creates disagreement between a client and a collaborator whose type we sometimes only know at runtime. You’ve experienced this if you’ve ever ended a 2-hour-long debugging session by yelling “You idiot! How did you expect that ever to work?!” You’ve discovered a fundamental contract disagreement.

While the LSP doesn’t receive the same attention as the Single Responsibility Principle, breaking the LSP leads to painful, costly mistakes. Understanding LSP, clarifying and respecting contracts helps you avoid this frustration.

I hope this helps.

Just a fun link today.

I read about Design by Contract first, didn’t understand it, then read about Test-Driven Development and began to think of TDD as a kind of DbC by example. Accordingly, I have respect for both practices and have even combined them on projects. Moreover, “Integrated Tests are a Scam” amounts to little more than Isolating Layers by Contract.

When I saw the Vigil programming language today, I fell in love. To quote its README:

When a Vigil program is executed, Vigil itself will monitor all oaths (implorations and swears) that have been made. If an oath is broken, the offending function (the caller in the case of implore and the callee in the case of swear) will be duly punished.

I know for sure I’ll try Vigil at the next Code Retreat.

A month ago I announced a new book. The book is now nearing completion.

In the past month I have published over 240 pages, filled with code, demonstrating how to test-drive the first feature of an Android app.

If you want to see how to bring the benefits of evolutionary design to Android, then this book is absolutely for you. In it, you’ll see example after example of designing with tests, refactoring, and running commentary on what goes in to making the design decisions I make. It’s my opportunity to show you how all the principles, practices, techniques and ideas I have about design work together.

• Get out of the simulator as quickly as possible
• Integrated tests are still a scam!
• Move details down the call stack and abstractions up the call stack
• How fast tests lead to great design

Android development can make Java programming fun again. In this book, I show you how I do it, so buy your copy today!

I really like Octopress, which is built on Jekyll. You can read a lot of articles about the advantages and disadvantages of pre-baked blogs, so I won’t bore you with those details. Instead, I’ll bore you on the subject of the one feature I miss with pre-baked blogs: scheduling posts for later publication.

When I switched to a pre-baked blogging tool like Octopress, I gave up the ability to upload a post, but publish it later. Well, I didn’t really give it up entirely, but pre-baking my blog means thinking of my blog as a static web site, rather than a dynamic one, which implies having to re-deploy every time I wanted to change its content. This makes scheduling posts in the future a bit more tricky.

Using Heroku and its read-only file system make it even trickier, since I can’t regenerate the blog in production.

I just wanted to share my solution with you, in case it interests you.

First, I added to Octopress the ability to generate the blog without future-dated posts. This looked difficult, especially with Octopress’s existing “preview mode” feature, but I discovered that Jekyll supports omitting future-dated posts directly with jekyll --no-future, so I augmented Octopress to use this feature. If you’d like to explore the details, click here.¹

Next, I needed a way to republish my Octopress site regularly in order to include new posts as their publication instant arrives. I asked my tweeps for ideas, and we agreed that we couldn’t get around having a machine Out There Somewhere that’s always on that would poll a git repository for changes, then regenerate and publish to Heroku. I settled on the following architecture.

I followed these basic steps:

1. Added an SSH public key from “Monitor/Staging” to “Production”, so that the former could push to the latter.
2. Installed a script into “Monitor/Staging” to, well, monitor, stage, then push.
3. Cloned my local git repository to “Integration” so that it will always be available to “Monitor/Staging”.

Complicated, sure, but–and you’ll tell me if you disagree–just barely sufficiently complicated, and no worse. I can handle that.

My workflow hasn’t changed much. I compose posts, preview, and push to “Integration” when I finish. “Monitor/Staging” runs the following script every 10 minutes.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

#! /bin/bash
pushd $HOME/Workspaces/blog.thecodewhisperer.com
# I have to do this by hand, apparently.
. .rvmrc

# I can't assume that I'm on the right branch
git checkout -q master
git pull -q origin master
git checkout -q publish
git merge -q master

# Check the diff /before/ regenerating, to avoid spurious
# timestamp differences
DIFF="$(git diff --stat publish heroku/master)"
NOW=`date`
if [ -n "$DIFF" ]; then
  echo "Publishing $NOW..."
  bundle exec rake generate
  git add -A && git commit -m "Published $NOW" && git push heroku publish:master
else
  echo "No need to publish at $NOW.";
fi
popd

I write posts to the branch master, and “Monitor/Staging” merges them to the branch publish, then deploys them to “Production”’s branch master.

Of course, I will monitor this closely over the next few days, looking for anomalies. In particular, I worry a little about what happens when “Monitor/Staging” can’t merge master to publish automatically. I suppose in that case I’ll have something to worry about, and in the worst case, no changes will publish to production, which could cause annoyance, but sounds like safe default behavior.

If you see any problems with this setup, please don’t keep them to yourself!

I’m pleased to announce that I have started writing a new book, entitled Responsible Design for Android. I really envision this as a series of short books, not wanting to repeat the 750-page behemoth that was JUnit Recipes.

In Part 1, Dancing with the Android SDK, I explore a sensible architecture for the basic Android app, emphasising context independence to avoid letting the Android framework swallow my app whole. I use tactics that have worked to great effect in working with older frameworks such as Servlets and EJB.

I toyed with the idea of writing an Android app in Ruby using Rhodes, but decided to return to my roots and Java, so if you’re writing Android apps in Java, and have run into maintenance or extensibility problems, then I’m writing this book for you.

I say “I’m writing”, because I’ve decided to use LeanPub to compose and publish the book. This means that you can read the book as I write it, and your feedback and questions could help direct its contents. As of this writing, I’ve published three versions of the book, and plan to publish a new version approximately twice per week until I’ve written enough.

The sooner you purchase the book, the less you pay, and once you purchase the book, you receive all future updates free of charge. I have already raised the minimum price of the book once, as I have published more content.

If you’d like to take a look, click here to download a sample chapter, then click here to buy the book.

I’m coding like it’s 2000, meaning in Java. I thought I’d never see anything new regarding writing a test that expects to catch a specific exception. I saw something new, and I wonder who else has independently discovered it.

Please add your comments at gist.github.com.

(If you can’t see the code snippet inline, then click here.)

I wish that I could take credit for this article, but I can’t. Instead, I have to credit two people: Lasse Koskela and Miško Hevery. I credit Lasse for writing the manuscript that led me to Miško’s article. Look for Lasse’s upcoming book Unit Testing in Java at Manning Publications’ site. Let me summarise Miško’s article here, then you can read the details at his blog.

Why would I simply summarise someone else’s article on this site? Isn’t that dishonest? Not in this case: Miško wrote essentially the same thing that I say over and over again in my own articles and in my training classes. I consider it unfortunate that he and I have never met nor worked together. We really should. You should read his stuff.

So… 10 ways to kill your design.

1. Instantiate Services wherever the hell you want.
2. Grab what you want when you want it.
3. Do real work in your constructors.
4. Publicise state.
5. Embrace singletons.
6. Make methods static. (Admittedly, this is more of a problem in Java/C# than Ruby/Python.)
7. Inherit implementation.
8. Reimplement polymorphism.
9. Mix Services and Values.
10. Keep conjunctions in your variable, method and class names.

Read more about the problems that these “techniques” cause.