Cognitive load is the mental effort required to follow code. It rises when a method presents too much information at once, especially when high-level business logic is mixed with low-level details such as validation and database access. The result is a reader whose working memory is overloaded, making confusion and errors more likely. section 2.3.1
Listing 2.1 A long story
public static User save(String firstName,
String lastName,
String email,
LocalDate birthDate,
String city) throws UserRegistrationException {
if (lastName == null || lastName.isBlank()) {
throw new UserRegistrationException("Last name is required");
}
if (birthDate == null) {
throw new UserRegistrationException("Birth date is required");
}
if (birthDate.isAfter(LocalDate.now()) ||
(Period.between(birthDate, LocalDate.now()).getYears() > 140)) {
throw new UserRegistrationException("Error on the birth date.");
}
if (email == null || email.isBlank()) {
throw new UserRegistrationException("Email is required");
}
String checkSql = "SELECT COUNT(*) FROM users WHERE email = ?";
String insertSql = """
INSERT INTO users (first_name, last_name, email, birth_date, city)
VALUES (?, ?, ?, ?, ?)""";
try (Connection conn = DriverManager.getConnection(
"jdbc:h2:mem:testdb", "sa", "")) {
try (PreparedStatement checkStmt = conn.prepareStatement(checkSql)) {
checkStmt.setString(1, email);
ResultSet rs = checkStmt.executeQuery();
if (rs.next() && rs.getInt(1) > 0) {
throw new UserRegistrationException("A user with this email " +
"already exists");
}
}
try (PreparedStatement insertStmt = conn.prepareStatement(insertSql)) {
insertStmt.setString(1, firstName);
insertStmt.setString(2, lastName);
insertStmt.setString(3, email);
insertStmt.setObject(4, birthDate);
insertStmt.setString(5, city);
insertStmt.executeUpdate();
}
return new User(firstName, lastName, email, birthDate, city);
} catch (SQLException e) {
throw new UserRegistrationException("Database error during " +
"user registration", e);
}
}
This registration method makes the cost visible: validation, date rules, SQL construction, and persistence all compete for attention in one long flow. section 2.3.1
Reducing load does not mean making every method smaller. A slightly longer method can be clearer when splitting it would force needless navigation. Extract code when a name reveals hidden intent, isolates a complex condition, preserves a consistent level of abstraction, or turns several details into one recognizable step. Do not extract a one-line simple chunk or a group of calls that is already clear. section 2.3.5 section 2.5
Use these signals to decide where code is cognitively heavy:
- A method has grown long, but judge readability rather than line count alone. section 2.3.5
- A responsibility is too broad for its abstraction level; low-level actions should stay narrow, while a higher-level method may coordinate a whole process. section 2.3.5
- A Boolean condition or nested branch contains several logical steps; replace it with a well-named operation when the name makes the decision easier to read. section 2.3.5
- A block combines distinct recognizable steps, such as validation and persistence or multiple system-boundary interactions. section 2.5
Name the decision, not its mechanics
A dense eligibility test forces the reader to retain several predicates at once. Replacing it with isEligible(user) turns those details into a named decision. The extraction earns its place when the name exposes intent; it should not merely relocate an already obvious expression. section 2.3.5
Structure also controls load across a larger flow. Action, scene, chapter, and table-of-contents methods create a readable hierarchy, while consistent formatting, intentional names, and introducing variables only when needed help readers retain the story. Treat these structures as aids to judgment, not quotas. section 2.5 section 2.6
The same tradeoff applies when changing programming styles. Functional pipelines can improve clarity, simplicity, and predictability, but long or dense pipelines may add cognitive cost. Keep imperative code where visible side effects, mutable state, or exception handling would become harder to understand after transformation. section 6.4
