principles:uniformity_principle
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous 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-10-18 22:00] (current) – +++ restored +++ christian | ||
---|---|---|---|
Line 12: | Line 12: | ||
* [[contexts: | * [[contexts: | ||
* [[contexts: | * [[contexts: | ||
+ | |||
===== Principle Statement ===== | ===== Principle Statement ===== | ||
Line 22: | Line 23: | ||
Striving for consistency and always using the same solutions also means that it can be a good idea to apply a " | 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. Furthermore uniformity in naming schemes is especially important for documentation. When referring to the same concept the same word has to be used. Synonyms are a source of misunderstanding. | ||
===== 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, | + | 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 70: | Line 75: | ||
* [[Keep It Simple Stupid]] (KISS): Although UP normally reduces complexity, sometimes UP demands more complex solutions because they are already applied elsewhere and for the sake of uniformity shall also be applied in simpler contexts where they would not be necessary. | * [[Keep It Simple Stupid]] (KISS): Although UP normally reduces complexity, sometimes UP demands more complex solutions because they are already applied elsewhere and for the sake of uniformity shall also be applied in simpler contexts where they would not be necessary. | ||
+ | * [[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]]. | * [[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]]. | ||
Line 94: | Line 100: | ||
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: // | 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. | ||
Line 107: | Line 117: | ||
Discuss this wiki article and the principle on the corresponding [[talk: | Discuss this wiki article and the principle on the corresponding [[talk: | ||
+ |
principles/uniformity_principle.txt · Last modified: 2021-10-18 22:00 by christian