This is an old revision of the document!
Table of Contents
Principle Of Separate Understandability (PSU)
Variants and Alternative Names
Context
Principle Statement
Each module shall be understandable on its own – without knowing anything about other modules.
Description
PSU means that:
- 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 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.
Rationale
When a module is separately understandable, it is easier to maintain, as no other modules have to be considered during maintenance. It is furthermore more testable, as a unit test can easily test only this particular module without requiring integration with other modules.
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
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:
Origin
This principle is newly proposed in this wiki. Nevertheless it is believed that it is not “new” in the sense that its a new insight. Its rather something that is commonly known but hasn't been expressed as a principle, yet.
Evidence
- Proposed (see origin)
Relations to Other Principles
Generalizations
Specializations
Contrary Principles
- Keep It Simple Stupid (KISS): Not to adhere to PSU is sometimes easier.
Complementary Principles
- 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.
Principle Collections
Example
Example 1: Parsing Data
Suppose a program parses data stored in an spreadsheet file. There are three classes:
SpreadsheetReader
: This reads the spreadsheet and createsDomainObject
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 aDomainObject
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.
This is a simple solution (see 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.