Differences

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

--- principles:principle_of_separate_understandability [2013-02-12 11:03] – strategies, statement, rationale, origin, evidence christian
+++ principles:principle_of_separate_understandability [2021-09-02 12:49] – old revision restored (2021-05-28 04:00) 65.21.179.175
@@ Line 33: / Line 33: @@
 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]]).
   * Find the right abstraction for the module that allows the functionality to stay here (see [[Model Principle|MP]]).
+===== Caveats =====
+See section [[#contrary principles]].
 ===== Origin =====
@@ Line 44: / Line 49: @@
 ===== Evidence =====
 /* Comment out what is not applicable and explain the rest: */
-  * [[wiki:Proposed]]
+  * [[wiki:Proposed]] (see origin)
 /*
@@ Line 65: / Line 70: @@
   * [[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 ====
@@ Line 73: / Line 79: @@
-===== Example =====
+===== Examples =====
+==== Example 1: Parsing Data ====
+Suppose a program parses data stored in an spreadsheet file. There are three classes:
+  * ''SpreadsheetReader'': This reads the spreadsheet and creates ''DomainObject'' objects.
+  * ''DomainObject'': This is the data which was contained in the spreadsheet and is now processed by the program in some way.
+  * ''SpreadsheetWriter'': This class takes a ''DomainObject'' and writes it back to the spreadsheet.
+In such a scenario it might be convenient to simplify ''SpreadsheetWriter'' by adding information about the spreadsheet to ''DomainObject''. This might be some cell coordinates for example. ''SpreadsheetReader'' can store them into the newly created ''DomainObject'' and ''SpreadsheetWriter'' uses the data to store the ''DomainObject'' to the correct position in the spreadsheet. The problematic method is ''DomainObject.getCellPositionInSpreadsheet()''.
+This is a simple solution (see [[Keep It Simple Stupid|KISS]]) but it violates PSU. ''DomainObject'' is not understandable on its own. It holds data (namely the cell position in the spreadsheet) that is only meaningful in the context of the other two modules. During maintenance this data could accidentally be altered (resulting in a corrupted output file). Maintenance effort is also increased simply by distracting the maintainers who might wonder what this data is and if it is relevant for their task.
+A better solution (wrt. PSU) would be to give ''SpreadSheetWriter'' the ability to determine the correct position in the spreadsheet itself. This is more complicated and may involve searching the spreadsheet for the correct position. But ''DomainObject'' is easier to understand and less prone to errors.
+==== Example 2: Dependent Private Methods ====
+In a module that computes results in a bowling game there might be a method ''strike()'' which returns true when the player has thrown a strike, i.e. hit all 10 pins with only one ball throw.
+<code java>
+private int ball;
+private int[] itsThrows = new int[21];
+private boolean strike()
+{
+    if (itsThrows[ball] == 10)
+    {
+        ball++;
+        return true;
+    }
+    return false;
+}
+</code>
+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 solution is better:
+<code java>
+private int rolls[] = new int[21];
+private boolean isStrike(int frameIndex)
+{
+    return rolls[frameIndex] == 10;
+}
+</code>
+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.
+  * First version: see ((http://www.objectmentor.com/resources/articles/xpepisode.htm)) or ((Robert C. Martin: //Agile Software Development, Principles, Patterns, and Practices//))
+  * Second version: see ((http://butunclebob.com/ArticleS.UncleBob.TheBowlingGameKata)) or ((http://www.slideshare.net/lalitkale/bowling-game-kata-by-robert-c-martin))
 ===== Description Status =====
 /* Choose one of the following and comment out the rest: */
 /*[[wiki:Stub]]*/
+/*[[wiki:Incomplete]]*/
-[[wiki:Incomplete]]
+[[wiki:Complete]]
-/*[[wiki:Complete]]*/
 ===== Further Reading =====
+===== Discussion =====
+Discuss this wiki article and the principle on the corresponding [[talk:principles:Principle Of Separate Understandability|talk page]].