What is ‘power-to-weight ratio’ of an API?

Question

In Bloch’s presentation, he said designer should look for good power-to-weight ratio for API. Moreover, he also stressed that ‘Conceptual weight more important than bulk’. I guess the weight is for ‘Conceptual weight’, bulk is for number of methods of a class.

But I couldn’t understand what ‘Conceptual weight’ is, what ‘power-to-weight ratio’ is. Welcome to any explanation!

Bloch gave an example: List.subList() has good 'power-to-weight ratio'. If clients wants to know an index of a sub list, he doesn't need to call a low 'p2w ratio' method indexOfSubList(a,b,e), instead, he could call List.subList(a,b).indexOf(e). Bloch thought this is 'power-to-weight ratio'.

Origin:

API Should Be As Small As Possible But No Smaller

• API should satisfy its requirements
• When in doubt leave it out
  • Functionality, classes, methods, parameters, etc.
  • You can always add, but you can never remove
• Conceptual weight more important than bulk
• Look for a good power-to-weight ratio

Answer 1

I'd interpret "conceptual weight" as the number of abstract concepts you have to learn and understand to use the API. Concepts usually map to public classes, while classes that are not public add to the bulk but not to the conceptual weight.

So if you put it technically, an API has a high conceptual weight if a typical client of the API has to explicitly use a lot of classes belonging to the API to work with it.

"good power-to-weight ratio" then means the API should use as few public classes as possible to offer as much functionality as possible. That means an API should:

• Not add concepts or abstractions of its own that are not present in the domain
• For complex domains, offer shortcuts to the most commonly needed functionality that allows a typical user to bypass the more complex parts of the domain