principles:easy_to_use_and_hard_to_misuse
Differences
This shows you the differences between two versions of the page.
| Both sides previous revisionPrevious revisionNext revision | Previous revisionNext revisionBoth sides next revision | ||
| principles:easy_to_use_and_hard_to_misuse [2013-02-18 17:24] – external edit 127.0.0.1 | principles:easy_to_use_and_hard_to_misuse [2021-10-13 08:19] – old revision restored (2021-09-02 12:27) 194.209.25.108 | ||
|---|---|---|---|
| Line 6: | Line 6: | ||
| ===== Context ===== | ===== Context ===== | ||
| /* fill in contexts here: */ | /* fill in contexts here: */ | ||
| - | * [[contexts: | + | * [[contexts: |
| + | * [[contexts: | ||
| + | * [[contexts: | ||
| ===== 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. | ||
| Line 25: | Line 35: | ||
| * Make the interface simple, so there will be fewer usage defects (see [[Keep It Simple Stupid|KISS]]) | * 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 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]]) | + | * Use consistent naming and models throughout the design (see [[Uniformity Principle|UP]] and [[Model Principle|MP]]) |
| * Avoid Preconditions (see [[Invariant Avoidance Principle]]) | * Avoid Preconditions (see [[Invariant Avoidance Principle]]) | ||
| * ... | * ... | ||
| Line 36: | Line 46: | ||
| ===== 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: |
| - | * [[wiki: | + | |
| + | /* * [[wiki: | ||
| * [[wiki: | * [[wiki: | ||
| * [[wiki: | * [[wiki: | ||
| Line 56: | Line 69: | ||
| * [[Principle of Least Surprise]] (PLS): A module is easy to use if there is no surprise in how it works. | * [[Principle of Least Surprise]] (PLS): A module is easy to use if there is no surprise in how it works. | ||
| - | * [[Uniformity Principle]] (UP): Uniform interfaces are easier to use than others. | ||
| ==== Contrary Principles ==== | ==== Contrary Principles ==== | ||
| Line 72: | Line 84: | ||
| {{page> | {{page> | ||
| - | ===== 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: | + | /*[[wiki: |
| - | /*[[wiki: | + | [[wiki: |
| / | / | ||
| Line 84: | Line 96: | ||
| * [[http:// | * [[http:// | ||
| + | * [[http:// | ||
| * [[http:// | * [[http:// | ||
| + | ===== Discussion ===== | ||
| + | |||
| + | Discuss this wiki article and the principle on the corresponding [[talk: | ||
principles/easy_to_use_and_hard_to_misuse.txt · Last modified: 2021-10-18 21:29 by christian