User Tools

Site Tools


principles:easy_to_use_and_hard_to_misuse

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
principles:easy_to_use_and_hard_to_misuse [2013-01-15 15:53] – +link christianprinciples:easy_to_use_and_hard_to_misuse [2021-10-18 21:29] (current) – +++ restored +++ christian
Line 3: Line 3:
 ===== Variants and Alternative Names ===== ===== Variants and Alternative Names =====
  
 +  * Pit of Success
 ===== Context ===== ===== Context =====
 /* fill in contexts here: */ /* fill in contexts here: */
-  * [[contexts:Object-Oriented Design]] +  * [[contexts:Object-Oriented Design]] 
 +  * [[contexts:API Design]] 
 +  * [[contexts:User Interface Design]]
  
  
 ===== Principle Statement ===== ===== Principle Statement =====
 +
 +A module shall be easy to use and hard to misuse.
  
  
 ===== Description ===== ===== Description =====
 +
 +A module is easy to use when the obvious way of using it is correct, when following established conventions means to use it correctly and the identifier of the module hints the correct usage. A module is hard to misuse, if misusing it requires more work than correct usage and when the compiler signals wrong usages.
  
  
 ===== Rationale ===== ===== Rationale =====
 +
 +This principle is common wisdom among API designers. APIs are used by many people and mainly by those who have not implemented the API. Few people read the documentation and will just try to use an API the obvious way. If the obvious way of using it is correct, if the API is easy to use, development will be more efficient. Furthermore if an API is hard to misuse, fewer mistakes will be made and which decreases the need for debugging and improves code quality.
 +
 +The same reasoning holds for every module, not just APIs. There are always other developers who will use a module. Either team members or successors. Moreover after a while one will not remember the details of a module anymore, the difference between other people and oneself will vanish. This means EUHM not only holds for APIs and not only for interfaces provided to the other team members but it holds for every single module.
  
  
 ===== Strategies ===== ===== Strategies =====
 +
 +This is a very general principle so there is a large variety of possible strategies to adhere more to this principle largely depending on the given design problem:
 +
 +  * Make use of static typing, so the compiler will report faults
 +  * Make the interface simple, so there will be fewer usage defects (see [[Keep It Simple Stupid|KISS]])
 +  * Use the same mechanisms wherever reasonably possible (see [[Uniformity Principle|UP]])
 +  * Use consistent naming and models throughout the design (see [[Uniformity Principle|UP]] and [[Model Principle|MP]])
 +  * Avoid Preconditions (see [[Invariant Avoidance Principle]])
 +  * ...
 +
 +
 +===== Caveats =====
 +
 +See section [[#contrary principles]].
  
  
 ===== Origin ===== ===== Origin =====
 +
 +The precise origin of the principle is unknown.
  
  
 ===== Evidence ===== ===== Evidence =====
 /* Comment out what is not applicable and explain the rest: */ /* Comment out what is not applicable and explain the rest: */
-/* + 
-  [[wiki:Proposed]] +[[wiki:Proposed]] 
-  * [[wiki:Examined]]+ 
 +/*  * [[wiki:Examined]]
   * [[wiki:Accepted]]   * [[wiki:Accepted]]
   * [[wiki:Questioned]]   * [[wiki:Questioned]]
Line 37: Line 64:
 ==== Generalizations ==== ==== Generalizations ====
  
-  * [[principles:Murphy's Law]]+  * [[Murphy's Law]] (ML):  Because of ML an interface should be crafted so it is easy to use and hard to misuse. EUHM is the application of ML to interfaces.
  
 ==== Specializations ==== ==== Specializations ====
  
-  * [[principles:Principle of Least Surprise]]+  * [[Principle of Least Surprise]] (PLS): A module is easy to use if there is no surprise in how it works.
  
 ==== Contrary Principles ==== ==== Contrary Principles ====
 +
 +  * [[Keep It Simple Stupid]] (KISS): Both principles, KISS and EUHM, are about simplicity. But while EUHM is about the simplicity of an interface, KISS is rather concerned with simplicity of the implementation. KISS is contrary in those cases where the solution which is easier to implement is not so easy to use or imposes further possibilities for misuse.
  
 ==== Complementary Principles ==== ==== Complementary Principles ====
  
-  * [[principles:Model Principle]] +  * [[Model Principle]] (MP): An interface that is crafted according to the model is easier to use than one that is not. 
-  * [[principles:Uniformity Principle]] +  * [[Invariant Avoidance Principle]] (IAP): One reason for a possible misuse of a module is an invariant. For example there might be a method which takes a list and an index where the index has to be within the bounds of the list. Each of these invariants imposes further possibilities for misuse of the module. So it is better to avoid them. 
-  * [[principles:Fail Fast]]+  * [[Information Hiding/Encapsulation]] (IH/E)A module should be properly encapsulated in order to make it easy to use and hard to misuse. 
 +  * [[Law of Leaky Abstractions]] (LLA): The more an abstraction leaks, the less it can be considered hard to misuse.
  
 ==== Principle Collections ==== ==== Principle Collections ====
Line 55: Line 85:
 {{page>collections:OOD Principle Language#Box}} {{page>collections:OOD Principle Language#Box}}
  
-===== Example =====+===== Examples =====
  
  
 ===== Description Status ===== ===== Description Status =====
 /* Choose one of the following and comment out the rest: */ /* Choose one of the following and comment out the rest: */
-[[wiki:Stub]] +/*[[wiki:Stub]]*
-/*[[wiki:Incomplete]]*/+[[wiki:Incomplete]]
 /*[[wiki:Complete]]*/ /*[[wiki:Complete]]*/
  
Line 67: Line 97:
  
   * [[http://programmer.97things.oreilly.com/wiki/index.php/Make_Interfaces_Easy_to_Use_Correctly_and_Hard_to_Use_Incorrectly|97things: Make Interfaces Easy to Use Correctly and Hard to Use Incorrectly]]   * [[http://programmer.97things.oreilly.com/wiki/index.php/Make_Interfaces_Easy_to_Use_Correctly_and_Hard_to_Use_Incorrectly|97things: Make Interfaces Easy to Use Correctly and Hard to Use Incorrectly]]
 +  * [[http://ozlabs.org/~rusty/index.cgi/tech/2008-03-18.html|APIs: "Easy to Use" vs "Hard to Misuse"]]
   * [[http://ozlabs.org/~rusty/index.cgi/tech/2008-03-30.html|How Do I Make This Hard to Misuse?]]   * [[http://ozlabs.org/~rusty/index.cgi/tech/2008-03-30.html|How Do I Make This Hard to Misuse?]]
 +
 +===== Discussion =====
 +
 +Discuss this wiki article and the principle on the corresponding [[talk:principles:Easy To Use And Hard To Misuse|talk page]].
 +
principles/easy_to_use_and_hard_to_misuse.1358261639.txt.gz · Last modified: 2013-05-20 12:45 (external edit)