principles:principle_of_separate_understandability
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revisionNext revisionBoth sides next revision | ||
principles:principle_of_separate_understandability [2013-02-12 12:29] – example 2 christian | principles:principle_of_separate_understandability [2013-10-07 10:21] – [Rationale] christian | ||
---|---|---|---|
Line 7: | Line 7: | ||
/* fill in contexts here: */ | /* fill in contexts here: */ | ||
* [[contexts: | * [[contexts: | ||
+ | * [[contexts: | ||
===== Principle Statement ===== | ===== Principle Statement ===== | ||
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 26: | Line 28: | ||
When a module is separately understandable, | When a module is separately understandable, | ||
- | Another point of view is that a violation | + | An important |
+ | * You have to find the implementation and jump there (modern IDEs help here but it takes time nevertheless) | ||
+ | * While doing so, you have to memorize the call and the context of the call. If implementation and call are not colocated (which is preferable but not always possible) you won't see the call anymore so you have to memorize it. | ||
+ | * Then you have to read the code and mentally inline it. | ||
+ | * If you could not memoroze everything, you might have to jump back and forth to do the job. | ||
+ | * After you did all that you have to jump back and continue reading the method with the call you just mentally inlined. | ||
+ | |||
+ | In a nutshell, if you have to mentally inline code, it would have been better if it was already inlined. The [[refactorings: | ||
+ | |||
+ | Another point of view is that a violation of PSU either means that a part of the functionality does not belong to that module or the module has the wrong abstraction. So this is a sign of a design that needs improvement. | ||
===== Strategies ===== | ===== Strategies ===== | ||
Line 33: | Line 44: | ||
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/ | + | * Move the conflicting functionality to another module where it fits better (see [[Tell don't Ask/ |
* 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 81: | ||
* [[Information Hiding/ | * [[Information Hiding/ | ||
- | * [[Low Coupling]] (LC): One kind of couplings are logical couplings. These are especially hard to detect but should be avoided. PSU describes one aspect | + | * [[Model Principle]] (MP): The model contains the only information that should be necessary to understand the module. And if the abstraction |
- | * [[Model Principle]] (MP): The model contains the only information that should be necessary | + | * [[Tell, don't Ask/ |
+ | * [[Low Coupling]] (LC): Not adhering | ||
==== Principle Collections ==== | ==== Principle Collections ==== | ||
Line 73: | Line 90: | ||
- | ===== Example | + | ===== Examples |
==== Example 1: Parsing Data ==== | ==== Example 1: Parsing Data ==== | ||
Line 107: | Line 124: | ||
</ | </ | ||
- | Here the method not only computed | + | Here the method not only computes |
- | The following | + | The following |
<code java> | <code java> | ||
private int rolls[] = new int[21]; | private int rolls[] = new int[21]; | ||
Line 118: | Line 135: | ||
} | } | ||
</ | </ | ||
- | Here no counting variable is increased in some way. Furthermore this method does not rely on a correctly set counter | + | Here no counting variable is increased in some way. Furthermore this method does not rely on a correctly set private |
This example is taken from Robert C. Martin. | This example is taken from Robert C. Martin. | ||
- | * First version: ((http:// | + | * First version: |
- | * Second version: ((http:// | + | * Second version: |
===== 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: | |
- | [[wiki: | + | [[wiki: |
- | + | ||
- | /*[[wiki: | + | |
===== Further Reading ===== | ===== Further Reading ===== | ||
+ | ===== Discussion ===== | ||
+ | Discuss this wiki article and the principle on the corresponding [[talk: |
principles/principle_of_separate_understandability.txt · Last modified: 2021-10-18 22:13 by christian