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 say that

• power = the amount of functionality provided by the API
• weight = the effort required to learn the API

Answer 2

I guess that an API with a good power-to-weight ratio is an API that offers a lot of functionality (power) while requiring little effort to properly work (weight) with it.

This is could be done via, for example, "Convention over Configuration". (Note this is just an example, and you can achieve this in many ways.)

It would be helpful a link to Bloch's presentation, he might be referring to something else :-)

Answer 3

He's referring to all the stuff you get from using an API. His example is for the collections API where each time you access it, you only get specific functionality. On the other hand, some API's will load much more stuff just to give you some functionality.

Answer 4

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