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 revisionBoth sides next revision
principles:principle_of_separate_understandability [2013-10-07 12:17] – christianprinciples:principle_of_separate_understandability [2013-10-07 14:26] – several minor improvements christian
Line 11: Line 11:
 ===== Principle Statement ===== ===== Principle Statement =====
  
-Each module shall be understandable on its own -- without knowing anything about other modules.+Each module shall be understandable on its own---without knowing anything about other modules.
  
  
Line 20: Line 20:
   * 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 (see [[#Example 2: Dependent Private Methods|example 2]]). 
-  * 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 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 (see [[#Example 3: Unnecessary State and Wrong Abstractions|example 3]]).
   * By looking at a single line of code it should be clear what it does without having to look up other code.   * By looking at a single line of code it should be clear what it does without having to look up other code.
  
Line 42: Line 42:
 ===== Strategies ===== ===== Strategies =====
  
-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 (see [[#Example 1: Parsing Data|example 1]]) or the module has the wrong abstraction ([[#Example 3: Unnecessary State and Wrong Abstractions|example 3]]). So strategies for making a solution more compliant with PSU are:
  
   * Move the conflicting functionality to another module where it fits better: [[refactorings:Move Field]], [[refactorings:Move Method]] (see [[Tell don't Ask/Information Expert|IE]], [[High Cohesion|HC]], and [[Model Principle|MP]]).   * Move the conflicting functionality to another module where it fits better: [[refactorings:Move Field]], [[refactorings:Move Method]] (see [[Tell don't Ask/Information Expert|IE]], [[High Cohesion|HC]], and [[Model Principle|MP]]).
Line 141: Line 141:
   * First version: see ((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: see ((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))
 +
  
 ==== Example 3: Unnecessary State and Wrong Abstractions ==== ==== Example 3: Unnecessary State and Wrong Abstractions ====
  
-Have a look at the following piece of code:+This example is also inspired by Robert C. Martin. Have a look at the following piece of code from [[resources:Clean Code]]:
 <code java> <code java>
 public String make(char candidate, int count) public String make(char candidate, int count)
Line 152: Line 153:
 } }
 </code> </code>
-What does it do? Certainly some information is missing. This piece of code is not separately understandable. You might feel the urge to ask for the implementation of ''createPluralDependentMessageParts'' as especially this method call is not separately understandable. OK, here it is:+What does it do? Certainly some information is missing to answer this question. This piece of code is not separately understandable. You might feel the urge to ask for the implementation of ''createPluralDependentMessageParts'' as especially this method call is not separately understandable. OK, here it is:
  
 <code java> <code java>
Line 237: Line 238:
 </code> </code>
  
-Only if you read all that code, you really get what's going on. Also if you started with some other method, you would not understand it. It's clear what ''thereIsOneLetter()'' does at the code is trivial. But you cannot understand //why// that code is there without knowing the rest. The problem cannot be solved by moving or renaming methods or fields. The abstraction of the methods is wrong. The methods are just groupings of code and have no distinct meaning. The uncommon naming scheme of the methods lacking an imperative might be an indicator for that. +Only if you read all that code, you really get what's going on. Also if you started with some other method, you would not understand it. It's clear what ''thereIsOneLetter()'' does as the code is trivial. But you cannot understand //why// that code is there without knowing the rest. 
  
-The functionality is buried in the class which is most obvious with the ''pluralModifier''. This value is used to construct a plural form in case it is needed by appending it to another value in the ''String.format'' statement. The concept of making a plural form is not present in the code. Rather the code centers around assigning values to variables.+The problem cannot be solved by moving or renaming methods or fields. The abstraction of the methods is wrong. The methods are just groupings of code and have no distinct meaning. The uncommon naming scheme of the methods lacking an imperative form of a verb might be an indicator for that.  
 + 
 +The functionality is buried in the class which is most obvious with the ''pluralModifier''. This value is used to construct a plural form by appending it to another value in the ''String.format'' statement. The concept of making a plural form is not present in the code. Rather the code centers around assigning values to variables.
  
 A better solution might be the following: A better solution might be the following:
Line 294: Line 297:
  
 ===== Further Reading ===== ===== Further Reading =====
 +
 +  * [[http://www.christian-rehn.de/2013/10/06/clean-code-und-das-principle-of-separate-understandability/|Clean Code und das Principle of Separate Understandability]]: Example 3 in more detail (German)
  
 ===== Discussion ===== ===== Discussion =====
  
 Discuss this wiki article and the principle on the corresponding [[talk:principles:Principle Of Separate Understandability|talk page]]. 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