Category:APIDesignPatterns:Clarity

From APIDesign

Good API has to support as much of cluelessness as possible. It has to be ready for use by people who see it for the first time, do not have time to understand how it really works, what are its important concepts. One way to tackle this goal is to create the API in a way that prevents misuses, make it accurate. This usually mean that each element (class, interface, method, field) visible in the API shall have exactly one meaning. Indeed, it is bad if it has less - meaningless elements in APIs are useless and distract attention from the other, more useful ones. However it is also bad if an element has more than one meaning. Why? Because the API is about communication, communication between the writer and the reader. If an element has more than one meaning in the head of the API creator, nobody can guarantee that the users of the API will discover all of them, especially if they are unlikely to know how much meanings they should search for.

Thus it is good if API Design Patterns create elements which has only one meaning. Then the pattern is said to have enough clarity, which seems like a very good thing.