principles:uniformity_principle
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:uniformity_principle [2021-05-19 09:49] – old revision restored (2021-05-11 17:19) 2a04:ac00:4:d29:5054:ff:fe00:d387 | principles:uniformity_principle [2021-09-02 12:50] – old revision restored (2021-05-19 09:48) 65.21.179.175 | ||
---|---|---|---|
Line 6: | Line 6: | ||
===== Context ===== | ===== Context ===== | ||
/* fill in contexts here: */ | /* fill in contexts here: */ | ||
- | * [[contexts: | + | * [[contexts: |
- | * [[contexts: | + | |
- | * [[contexts: | + | |
- | * [[contexts: | + | |
- | * [[contexts: | + | |
- | * [[contexts: | + | |
- | ===== Principle Statement ===== | ||
- | Solve similar problems in the same way. | + | ===== Principle Statement ===== |
+ | Solve similar problems the same way. | ||
===== Description ===== | ===== Description ===== | ||
- | |||
- | Software design comprises many similar tasks. There are plenty of design decisions that are similar to ones taken before. UP tells that a design is good when similar design problems are solved the same way. UP can be applied to a large variety of problems: naming identifiers, | ||
- | |||
- | Striving for consistency and always using the same solutions also means that it can be a good idea to apply a " | ||
- | |||
- | For documentation UP means to have a consistent documentation structure such that a certain piece of information can be found easily. | ||
===== Rationale ===== | ===== Rationale ===== | ||
- | |||
- | Following UP reduces the number of different solutions. There are fewer concepts to learn, fewer problems to solve and fewer kinds of defects that can occur. So the developers, whether the original ones or the maintainers, | ||
- | |||
- | Documentation which follows a fixed structure helps you find a certain piece of information faster because as soon as you have understood the structure you know where to look. | ||
Line 37: | Line 22: | ||
* Use the same naming scheme everywhere | * Use the same naming scheme everywhere | ||
- | * Use the same techniques, mechanisms, libraries, | + | * Use the same techniques and mechanisms |
* In similar methods use the same order of parameters | * In similar methods use the same order of parameters | ||
- | |||
- | |||
===== Caveats ===== | ===== Caveats ===== | ||
- | UP demands solving similar problems in the //same way// and not just in a similar way. This is crucial as subtle differences can be dangerous. These small differences are created easily. Sometimes it is impossible to do two things exactly the same way. And also over time two modules may slowly diverge. So it is sometimes better to have two modules work completely differently than to allow for these subtle differences as they easily lead to misconceptions and mistakes (see [[Murphy' | + | See section [[#contrary principles]]. |
- | + | ||
- | See also section [[#contrary principles]]. | + | |
===== Origin ===== | ===== Origin ===== | ||
- | |||
- | This principle is newly proposed here. Nevertheless the idea is not new and should be pretty intuitive to every developer. | ||
Line 66: | Line 45: | ||
==== Generalizations ==== | ==== Generalizations ==== | ||
- | * [[Murphy' | + | * [[Easy to Use and Hard to Misuse]] (EUHM): Uniform interfaces |
==== Specializations ==== | ==== Specializations ==== | ||
Line 72: | Line 51: | ||
==== Contrary Principles ==== | ==== Contrary Principles ==== | ||
- | Note that UP can be contrary to virtually every other principle as it demands neglecting other principles in favor of uniformity. | + | |
- | + | * [[Model Principle]] (MP): UP may demand adhering to a certain naming scheme, which may not be best with respect to MP. | |
- | | + | |
- | * [[More Is More Complex]] (MIMC): Documenting something because of UP may result in unnecessary documentation. There may be more concise ways of documentation. | + | |
- | * [[Model Principle]] (MP): UP may demand adhering to a certain naming scheme, which may not be best with respect to MP. See [[#example 1: naming schemes]]. | + | |
==== Complementary Principles ==== | ==== Complementary Principles ==== | ||
- | * [[Principle of Least Surprise]] (PLS): When applying UP, PLS should also be considered for naming modules. | + | * [[Principle of Least Surprise]] (PLS): When applying UP, PLS should also be considered for naming modules. |
Line 88: | Line 63: | ||
{{page> | {{page> | ||
- | + | ===== Example ===== | |
- | ===== Examples ===== | + | |
- | + | ||
- | ==== Example | + | |
- | + | ||
- | A typical example of the application of UP is the naming of method identifiers for common container classes like [[glossary: | + | |
- | + | ||
- | Stacks typically have the methods '' | + | |
- | + | ||
- | Queues on the other hand typically have the methods '' | + | |
- | + | ||
- | A third possibility is to find a common abstraction and to apply a very general naming scheme to all descendant classes (stack classes, queue classes and others). This is the way it is done in Eiffel((see Bertrand Meyer: // | + | |
- | + | ||
- | ==== Example 2: This Wiki ==== | + | |
- | + | ||
- | This wiki has a certain structure which is uniform across all principles. Each principle description has the same sections with the same kind of information. This makes looking up principles much easier because one can directly jump to those sections containing the needed information. To mitigate the problem of unnecessary documentation (i.e. MIMC violations) sections without additional information are left blank instead of describing something obvious. | + | |
===== 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: |
/ | / | ||
===== Further Reading ===== | ===== Further Reading ===== | ||
- | ===== Discussion ===== | ||
- | Discuss this wiki article and the principle on the corresponding [[talk: |
principles/uniformity_principle.txt · Last modified: 2021-10-18 22:00 by christian