Principles Wiki

User Tools

Site Tools

You are here: Principles Wiki » Principles » Principle Of Separate Understandability (PSU)
principles:principle_of_separate_understandability

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
Next revisionBoth sides next revision
principles:principle_of_separate_understandability [2013-02-12 12:29] – example 2 christianprinciples:principle_of_separate_understandability [2013-07-09 13:19] – [Description] christian
Line 17: Line 17:
  
 PSU means that: PSU means that:
 +  * By looking at a class its purpose should be clear.
   * By looking at the public methods of a class it should be clear why they are there. That means there should be no method that is only there because a specific other module needs it.   * By looking at the public methods of a class it should be clear why they are there. That means there should be no method that is only there because a specific other module needs it.
   * By looking at the implementation of a module it should be clear how it works and why it was done that way. That means there should be no code that is solely there in order to make another module work.   * By looking at the implementation of a module it should be clear how it works and why it was done that way. That means there should be no code that is solely there in order to make another module work.
   * By looking at a private method it should be clear what it does. That means there should be no (private) method that is only meaningful in the context of another method.   * By looking at a private method it should be clear what it does. That means there should be no (private) method that is only meaningful in the context of another method.
 +  * By looking at a method invocation it should be clear what happens, why the parameters are there, and what they specify. It should not be necessary to look up the method implementation. 
 +  * By looking at a single line of code it should be clear what it does without having to look up other code.
  
 ===== Rationale ===== ===== Rationale =====
Line 33: Line 35:
 When a module does not comply with PSU, this means that either a part of the functionality of the module does not belong here or the module has the wrong abstraction. So strategies for making a solution more compliant with PSU are: When a module does not comply with PSU, this means that either a part of the functionality of the module does not belong here or the module has the wrong abstraction. So strategies for making a solution more compliant with PSU are:
  
-  * Move the conflicting functionality to another module where it fits better (see [[Tell don't Ask/Information Expert|IE]]).+  * Move the conflicting functionality to another module where it fits better (see [[Tell don't Ask/Information Expert|IE]], [[High Cohesion|HC]], and [[Model Principle|MP]]).
   * Build up a new module for the conflicting functionality (see [[High Cohesion|HC]]).   * Build up a new module for the conflicting functionality (see [[High Cohesion|HC]]).
   * Find the right abstraction for the module that allows the functionality to stay here (see [[Model Principle|MP]]).   * Find the right abstraction for the module that allows the functionality to stay here (see [[Model Principle|MP]]).
 +
 +===== Caveats =====
 +
 +See section [[#contrary principles]].
 +
  
 ===== Origin ===== ===== Origin =====
Line 65: Line 72:
  
   * [[Information Hiding/Encapsulation]] (IH/E): PSU is about constructing a module such that its inner workings (and its usage also) can be understood without knowledge about other modules. IH/E on the other hand is about constructing a module in a way that hides the inner workings so it can be used without knowing //them//.   * [[Information Hiding/Encapsulation]] (IH/E): PSU is about constructing a module such that its inner workings (and its usage also) can be understood without knowledge about other modules. IH/E on the other hand is about constructing a module in a way that hides the inner workings so it can be used without knowing //them//.
-  * [[Low Coupling]] (LC): One kind of couplings are logical couplings. These are especially hard to detect but should be avoided. PSU describes one aspect of these logical couplings, whereas LC relates this kind of coupling to others. +  * [[Model Principle]] (MP): The model contains the only information that should be necessary to understand the module. And if the abstraction of the model is wrong, MP helps getting it right. 
-  * [[Model Principle]] (MP): The model contains the only information that should be necessary to understand the module. +  * [[Tell, don't Ask/Information Expert]] (TdA/IE): At its heart PSU is about responsibility assignment. When a module is not separately understandable, this means that a responsibility is scattered across several modules. TdA/IE gives another aspect of responsibility assignment. 
 +  * [[Low Coupling]] (LC): Not adhering to PSU means that responsibilities are scattered across several modules. This typically also means increased coupling.
  
 ==== Principle Collections ==== ==== Principle Collections ====
Line 73: Line 81:
  
  
-===== Example =====+===== Examples =====
  
 ==== Example 1: Parsing Data ==== ==== Example 1: Parsing Data ====
Line 107: Line 115:
 </code> </code>
  
-Here the method not only computed if the current throw is a strike but also advances the counting variable ''ball''. This is only meaningful in the context of another module. If this is correct behavior or a defect cannot be told solely by looking at this method. Should ball be increased by 1 or 2? Should it also be increased when the throw is not a strike? Should it be increased at all? It cannot be told without looking at other parts of the code. So this method violates PSU.+Here the method not only computes if the current throw is a strike or not but also advances the counting variable ''ball''. This is only meaningful in the context of another method. If this is correct behavior or a defect cannot be told solely by looking at this method. Should ball be increased by 1 or 2? Should it also be increased when the throw is not a strike? Should it be increased at all? It cannot be told without looking at other parts of the code. So this method violates PSU.
  
-The following solutuion is better:+The following solution is better:
 <code java> <code java>
 private int rolls[] = new int[21]; private int rolls[] = new int[21];
Line 118: Line 126:
 } }
 </code> </code>
-Here no counting variable is increased in some way. Furthermore this  method does not rely on a correctly set counter variable but gets a parameter.+Here no counting variable is increased in some way. Furthermore this  method does not rely on a correctly set private variable but gets a parameter.
  
 This example is taken from Robert C. Martin.  This example is taken from Robert C. Martin. 
-  * First version: ((http://www.objectmentor.com/resources/articles/xpepisode.htm)) or ((Robert C. Martin: //Agile Software Development, Principles, Patterns, and Practices//)) +  * First version: see ((http://www.objectmentor.com/resources/articles/xpepisode.htm)) or ((Robert C. Martin: //Agile Software Development, Principles, Patterns, and Practices//)) 
-  * Second version: ((http://butunclebob.com/ArticleS.UncleBob.TheBowlingGameKata)) or ((http://www.slideshare.net/lalitkale/bowling-game-kata-by-robert-c-martin))+  * Second version: see ((http://butunclebob.com/ArticleS.UncleBob.TheBowlingGameKata)) or ((http://www.slideshare.net/lalitkale/bowling-game-kata-by-robert-c-martin))
  
 ===== 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]]*/+
  
 ===== Further Reading ===== ===== Further Reading =====
  
 +===== Discussion =====
  
 +Discuss this wiki article and the principle on the corresponding [[talk:principles:Principle Of Separate Understandability|talk page]].
principles/principle_of_separate_understandability.txt · Last modified: 2021-10-18 22:13 by christian