User Tools

Site Tools


principles:principle_of_separate_understandability

This is an old revision of the document!


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 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 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 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

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.

An important aspect of PSU is readability or rather understandability. If a module—say a method—requires to understand several other modules (other methods, the usage of certain attributes, the idea of the whole class, …), a much larger part of the code has to be read and kept in memory. And if a method call is not separately understandable, the reader of the code will have to jump to the implementation of the method in order to see what's going on. This is unnecessarily time consuming:

  • 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 method extraction in fact was harmful to readability and not beneficial. Note that not extracting a method needn't be the best solution to the problem. Often renaming the extracted method already does the job. Maybe this also hints that not the right piece of code has been extracted.

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:

  • Move the conflicting functionality to another module where it fits better: Move Field, Move Method (see IE, HC, and MP).
  • Build up a new module for the conflicting functionality: Extract Method, Extract Class (see HC).
  • Find the right abstraction for the module that allows the functionality to stay here (see MP).
  • Find a name which properly describes the abstraction of the module: Rename Module (MP).

Caveats

See section contrary principles.

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

Relations to Other Principles

Generalizations

Specializations

Contrary Principles

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.
  • 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.
  • 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

OOD Principle Language
General Principles
ML KISS MIMC DRY GP RoE
Modularization Principles
MP HC ECV
Module Communication Principles
TdA/IE LC DIP
Interface Design Principles
EUHM PLS UP
Internal Module Design Principles
IH/E IAP LSP PSU

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 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.

private int ball;
private int[] itsThrows = new int[21];
 
private boolean strike()
{
    if (itsThrows[ball] == 10)
    {
        ball++;
        return true;
    }
    return false;
}

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:

private int rolls[] = new int[21];
 
private boolean isStrike(int frameIndex)
{
    return rolls[frameIndex] == 10;
}

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 1) or 2)
  • Second version: see 3) or 4)

Description Status

Further Reading

Discussion

Discuss this wiki article and the principle on the corresponding talk page.

principles/principle_of_separate_understandability.1630579764.txt.gz · Last modified: 2021-09-02 12:49 by 65.21.179.175