Choice is good.  Except when it cripples our ability to make decisions.

At a recent meeting of the New York Scala Enthusiasts (the other NYSE), Nathan Hamblen (a.k.a. Coderspiel) spoke about building the Databinder Dispatch HTTP library in Scala.  Databinder makes use of Scala's support for symbols as method names, which leads to HTTP code that looks similar to a URL:

val db = :/("databinder.net")

http(db / "dispatch" / "Guide" >>> System.out)

One challenge with this design is that it can be difficult for someone new to understand the library without first learning all the symbols.  When asked if he planned to add aliases for these methods using words instead of symbols (e.g. GET, POST, DELETE), Nathan had a thought-provoking response (I'm paraphrasing): He said he didn't like presenting two ways to do one thing in because it can lead to conflict in how people use the API in a codebase.  For example, your code might use the words while mine uses the symbols, requiring any code reader to recall that these two different expressions really mean the same thing.

This doesn't just impact any future code readers - it can impair the writers as well.  If you were new to the code and saw two different ways to say the same thing, how would you decide which one to use?  This decision can be overwhelming to new team members, even paralyzing.  Which way is better, and why?

Authors Chip and Dan Heath recount several studies concerning decision-making in their book Made to Stick: Why Some Ideas Survive and Others Die.  One study presented students the choice of studying or attending a one-night only lecture by their favorite author.  Interestingly, when students were then presented with a third option of seeing a foreign film they've been wanting to see, more students decided to forego the fun options and study.  "Giving students two good alternatives to studying, rather than one, paradoxically makes them less likely to choose either.  This behavior isn't 'rational', but it is human."  See the "Simple" chapter in the book for the full details of the study.

In his talk "Responsive Design", Kent Beck recommends looking to core, shared principles to help make these decisions.  With these principles (for example, "Don't Repeat Yourself", "Never lose a data write under load", "Make code look like a URL"), we can avoid decision paralysis and turn to the principles to help us reduce our set of choices.  The Heaths recommend making these principles simple to help to remind people what's important and avoid making bad choices.

Providing only one way to do something may cause your colleagues, code readers, or API users to disagree with your choices, but it prevents decision paralysis - which can be much worse than a disagreement.