It is a mostly well-known fact, yet nearly always overlooked, that large software teams underperform small ones. I’ve been building software professionally for 15 years and continue to be amazed by this simple truth. Fred Brooks, of course, canonized this thinking in his “bible of software engineering”, The Mythical Man-Month, but as Brooks has been known to say of his book, “everybody quotes it, some people read it, and a few people go by it.” The urge to add bodies to expedite software development is just too strong to resist.

This isn’t surprising. It’s human nature to apply learned patterns to problems. You need to build a stone wall to defend your town? Add labor (preferably slave) and the project pace quickens. Trying to hunt a bison? Get all of the able-bodied men to assist. Work, broadly defined, is a function of man-hours. The more men, the more man-hours are chewed-up per day, and the faster we all finish and go home.

Unfortunately, software development works precisely the opposite. Throw more people at an effort and the pace drags. And once the pace drags, the human instinct takes over and the urge to add “resources” to an effort takes off – thereby slowing it down further. Brook’s Law is a law for a reason, it’s like gravity—try as you may to overcome it, you’re going to get pulled down.

So why is this the case? At the most basic level, it’s of course about communication. More people require more communication. Think factorials. Communication isn’t inherently bad, but it’s time consuming and fraught with inconsistencies and errors (but Tom told me that feature was taken out of this version of the app). It’s also about decision-making. Larger teams often have more than one decision-maker, which is deadly. Show me a medium to large scale software development effort with more than one decision-maker and I will show you a future disappointment.

OK, so if communication and shared decision making are at fault, then the optimal team size for a development effort is one, correct? Well, sort of. One talented designer / developer with an innate understanding of the product they are trying to develop is the optimal team size, yes. (Chris Dary from Arc90 is one example of that – he single-handedly built the first version of Kindling and took it from idea, to prototype to beta version in weeks. No debating features, no iterating on logos (make it bigger!), no defending decisions.) However, you probably recognize a logical constraint with this, which is that these people and conditions are very rare, and software development, like every other human endeavor, is becoming more and more specialized. It’s hard to find all of the required skill in one human – a product visionary that knows javascript frameworks, can configure apache, design interactions and write SQL. So let me rephrase the optimal team size for any software effort:

The optimal team size for any software effort is precisely enough people to cover all of the required skills of that effort and not a single human more.

Follow this rule and you will be optimally positioned for success 100% of the time.

Besides reducing the team size down to the bare minimum, are there other things you can do to resist the tug of Brook’s Law? Thankfully, there are:

• Have a fully empowered single Product Manager. This is probably the most controversial. Years ago after reading the (must-read) Dreaming In Code, I wrote this:
  

  Good software requires a singular vision, and a singular keeper of that vision. The Chandler effort was plagued by ambiguity from the start, what were they building? Did anyone know? Did all of them have the same vision? Any successful software efforts that I’ve been a part of had either a benevolent dictator, a less-than-benevolent dictator or a team with a shared brain. Another manifestation of this is the fact that often great software is built by a team of one – where the vision is never lost in the details of communication. Even worse for the Chandler team, not only did the team not have a shared vision of what they were striving towards, it seemed that no individual did either. Rosenberg articulates this point perfectly later in the book:

  “…software development takes simple elegant visions and atomizes them, separating them into millions of implementation details and interface choices and compromises. The art of making software well is, in a sense, the ability to send a vision through that atomizer in such a way that it can eventually be put back together…”

  A good litmus test here would be to walk around and talk to your software team, asking each member what they’re building. Force them to describe the vision, not the details of a specific task. If you hear entirely different things from the team, you’re likely in trouble.

  That comment received the most feedback, as people were uncomfortable with the notion of one decision-maker. But I believe that even more today than I did then.

• Document versus communicate. This is a lesson I’ve learned over and over. Communication and discussion is fine, but once a call is made, immediately capture it as fact. That might be in a Requirements Document or better yet as a ticket in an issue tracking system, but don’t leave decisions floating in the ether. Decisions are gold, when you arrive at one, treat it as such.
• Design first, build later. And I don’t only mean wireframe and comps, I mean design everything before writing code. The architecture. The API. Whatever can be thought-through ahead of coding pays dividends later. This is such an obvious and straight-forward fact that I see ignored repeatedly. Design is decision-making and arriving at decisions early is the goal. Having a fully documented and stubbed API, for example, represents tens of hours of thinking and hundreds of decisions that, once in place, empower development teams to build without communicating with each other. And communication is the enemy of productivity.
• Use good issue tracking. It’s almost 2011, get yourself a decent issue tracking system. Imagine a fireman using a dull axe or a painter using worn brushes. Building software is an exercise in communication and the issue tracking system is where nearly all of this communication plays out. That’s how important it is.

But the absolute, don’t-forget-it, most important thing is team size. The optimal team size for any software effort is precisely enough people to cover all of the required skills of that effort and not a single human more. Ignore this at your peril.

We’ve been using Restlet for a few years now, so we’ve had the opportunity to introduce a few employees to it. There are a few questions that invariably come up as people starting learning Restlet; I thought it might be helpful to post them here, with the answers, for reference.

Note: answers are written against Restlet 1.1.

Q: How do I access URL query parameters?

There are two answers:

A1, for specific expected query parameters

The easiest way to work with query parameters which your application expects and which have a specific name is to tell your Routes about them.

Typically, you create a Router in an Application, and then add Routes to it using attach(String uriPattern, Class<? extends Resource> targetClass) . Calling this method returns a newly created Route which represents your mapping of a path to a class.

To have the Route extract a parameter from the URL for each request, call extractQuery(String attribute, String parameter, boolean first), like so:

router.attach("collection", MyCollectionResource.class)
.extractQuery("page", "page", true)
.extractQuery("perPage", "perPage", true);

Once that’s all set, when you’re writing your Resource and want to access that parameter, Restlet automatically puts it in the Map returned by Request.getAttributes().

So you can access your parameter like so:

getRequest().getAttributes().get('page');

Keep in mind that if the parameter isn’t specified for a given request, the result of the get() call will be null. Also, if you pass the value false as the last parameter to extractQuery(), the result may be a List.

A2, for arbitrary query parameters

Of course, sometimes you need to just access an arbitrary query parameter on the fly, or check whether one was specified or not. This is easily done anywhere in a Resource, using getQuery(), like so:

String fooParam = getQuery().getFirstValue('foo');

It can seem odd at first that getQuery() returns a “Form”, but the Form class turns out to be a good fit for this use case, and a very helpful class. For example, it has the useful method getValuesMap() to get a Map containing all of its values.

Q: How do I access request headers?

A1, for standard HTTP headers

Restlet is intended to be a comprehensive Java API for building and calling RESTful applications — and not necessarily RESTful web applications. Therefore, Restlet provides classes and methods which represent all the commonly used RESTful paradigms, semantically.

So, to access the values of most standard HTTP headers, you call the appropriate method of the Request class.

A quick reference:

(This table is not exhaustive, it’s an example to illustrate how Restlet works.)

The Restlet wiki contains the page Mapping HTTP semantics, which exhaustively maps HTTP semantics to Restlet. Note that it targets Restlet 1.2.

A2, for custom HTTP headers

Of course, a client can send any header as a custom header, and you may need to check if any have been sent, and get their values. For this reason, Restlet puts all request headers into a Form, which is accessible via a special key in the request attributes.

For example:

Form requestHeaders = (Form) getRequest().getAttributes().get('org.restlet.http.headers');
String myAwesomenessHeader = requestHeaders.getFirstValue('X-Awesomeness');

Q: How do I set response headers?

Response headers works the same as request headers: class methods for standard headers, and a special key in Response attributes for custom headers.

A1, for standard HTTP headers

(This table is not exhaustive, it’s an example to illustrate how Restlet works.)

Some headers are derived from the response representation:

(This table is not exhaustive, it’s an example to illustrate how Restlet works.)

A2, for custom HTTP headers

Form responseHeaders = (Form) getResponse().getAttributes().get('org.restlet.http.headers');
if (responseHeaders == null)
{
responseHeaders = new Form();
getResponse().getAttributes().put('org.restlet.http.headers', responseHeaders);
}
responseHeaders.add('X-Awesomeness', 'true');

Updated on March 23, 2009 to use Form.add() instead of Form.createEntry(), which doesn’t seem to produce the desired effect.

Updated on March 23, 2009 to use Resource.getQuery() instead of getRequest().getResourceRef().getQueryAsForm(); added a note about the relevant version of Restlet; added a link to a wiki page mapping HTTP to Restlet. Thanks Jérôme!