Intent vs. Implementation

The dichotomy between intent and implementation is pivotal in the realm of software development. It is the difference between understanding what the code is supposed to achieve versus how it achieves it. This distinction is not merely semantic; it has profound implications for the readability, maintainability, and scalability of software systems. In this section, we will delve into the importance of distinguishing between intent and implementation, exploring how this distinction can be applied in practice to improve the quality of software.

The Problem of Implementation Leakage

Implementation leakage occurs when the internal mechanics of a module—such as data structures, transport protocols, or specific algorithms—are visible in its public interface or identifiers. This leakage can make the system rigid and difficult to modify because changes to the internal logic may require changes to the public API, affecting all dependent components. For instance, a method named uploadToS3Bucket not only reveals its implementation detail (uploading to an S3 bucket) but also tightly couples the caller with the specific infrastructure (S3), making any future change to the storage solution cumbersome.

The Power of Intent-Revealing Names

Names that describe what the code achieves, rather than how it works, are termed intent-revealing names. These names allow for immediate domain mapping, reducing cognitive load by aligning the code’s structure with the business domain’s expectations. For example, renaming a variable from arr to authorizedRoles or a function from check to identityHasAccess transforms the code from a technical document into a domain-specific narrative, facilitating local reasoning and collective code ownership.

Before and After: A Practical Example

Consider the following JavaScript example:

// BEFORE: Ambiguous & Implementation-focused
let arr = ["admin", "editor"];
function check(s, a) {
  for(let i=0; i < a.length; i++) {
    if (a[i] === s) return true;
  }
  return false;
}

// AFTER: Expressing Intent and Business Domain
const authorizedRoles = ["admin", "editor"];
function identityHasAccess(roleName, rolesList) {
  return rolesList.includes(roleName);
}

In the ‘before’ example, the focus is on the implementation (looping through an array), whereas in the ‘after’ example, the intent is clear (checking if an identity has access based on roles), making the code more readable and maintainable.

Reducing Cognitive Load

Cognitive load in software development refers to the amount of mental effort required to understand a piece of code. Human working memory is limited, capable of holding roughly 4 to 7 discrete ‘chunks’ of information. By using intent-revealing names and reducing implementation leakage, developers can significantly lower the cognitive load associated with their code, making it easier for themselves and others to understand and modify the system in the future.

Conclusion

Distinguishing between intent and implementation is crucial for writing clean, maintainable code. By focusing on what the code is supposed to achieve rather than how it achieves it, developers can create software systems that are more readable, scalable, and easier to maintain. This approach not only reduces cognitive load and technical debt but also fosters a culture of collective code ownership, where every member of the team can contribute to and understand the codebase with ease.

Sources

No external sources were cited in this section.