User Tools

Site Tools


principles:uniformity_principle

Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Last revision Both sides next revision
principles:uniformity_principle [2016-07-10 22:23]
christian [Context]
principles:uniformity_principle [2016-07-10 22:58]
christian UP for documentation
Line 12: Line 12:
   * [[contexts:​Implementation]]   * [[contexts:​Implementation]]
   * [[contexts:​Documentation]]   * [[contexts:​Documentation]]
 +
 ===== 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 "​bad"​ or less-well suited solution for the sake of consistency. If for example a bad naming scheme is used throughout the whole project, it is advisable not to break it as an inconsistency in the naming scheme would be worse than applying the bad naming scheme everywhere. Striving for consistency and always using the same solutions also means that it can be a good idea to apply a "​bad"​ or less-well suited solution for the sake of consistency. If for example a bad naming scheme is used throughout the whole project, it is advisable not to break it as an inconsistency in the naming scheme would be worse than applying the bad naming scheme everywhere.
 +
 +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,​ have an easier task in creating, understanding,​ and maintaining the software. By reducing variety in the design, the software becomes ​easier ​(see [[Keep It Simple Stupid|KISS]]).+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,​ have an easier task in creating, understanding,​ and maintaining the software. By reducing variety in the design, the software becomes ​simpler ​(see [[Keep It Simple Stupid|KISS]])
 + 
 +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: //​[[http://​en.wikipedia.org/​wiki/​Object-Oriented%20Software%20Construction|Object-Oriented Software Construction]]//,​ p. 127)). Here there the method names are ''​put'',​ ''​remove''​ and ''​item''​ regardless of the concrete data structure. This is contrary to MP but creates a uniform naming scheme throughout the API. So there is less uniformity across APIs but stronger uniformity within the API. MP and UP are here contrary too. For PLS this means that a developer who is used to this philosophy is never surprised by having these methods. But developers new to it might be nevertheless. 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: //​[[http://​en.wikipedia.org/​wiki/​Object-Oriented%20Software%20Construction|Object-Oriented Software Construction]]//,​ p. 127)). Here there the method names are ''​put'',​ ''​remove''​ and ''​item''​ regardless of the concrete data structure. This is contrary to MP but creates a uniform naming scheme throughout the API. So there is less uniformity across APIs but stronger uniformity within the API. MP and UP are here contrary too. For PLS this means that a developer who is used to this philosophy is never surprised by having these methods. But developers new to it might be nevertheless.
 +
 +==== 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.
  
  
principles/uniformity_principle.txt · Last modified: 2016-07-11 22:59 by christian