Static 1 source · 10m ago

How to name things

The article "How to Name Things" by Koleman Nix emphasizes that effective naming in software engineering is crucial for clear thinking and communication. Nix argues that vague language often indicates a lack of clarity in thought, and that every name—from local variables to API endpoints—serves as a form of communication to colleagues, future selves, and even language models. He posits that the perceived degradation of AI performance in codebases is often due to a "lossy expansion" of unclear terminology, rather than the model itself worsening. This highlights the necessity of refining terminology to maintain code clarity and system sustainability. Nix advocates for a deep, context-aware approach to naming, prioritizing semantic understanding over rigid rules. He critiques the desire for consistency as a virtue in itself, suggesting it can lead to avoiding deeper engagement with concepts. Instead, he champions intellectual empathy and understanding the essence of what is being named, considering its relationship to other concepts and its impact on future readers or programs. He illustrates this with examples like `created_at` versus `uploaded_at` and the `mergeTargetValuesIntoSourceTemplate` function, arguing that names should reflect the fundamental nature of an item, not just its immediate use case.

AI Signal Decode

The core argument is that naming is a direct reflection of cognitive clarity. Nix stresses that imprecise language in code—whether for variables, functions, or entire systems—correlates with muddled thinking. This concept is particularly relevant with the rise of AI coding assistants; clear, well-defined names provide context that aids AI, while ambiguous terminology leads to "lossy expansion," where the AI interpolates incorrectly based on unclear initial signals. Therefore, consistently refining names is paramount for both human maintainability and effective AI collaboration.

Nix critiques the common desire for rigid naming conventions, labeling it a "craving for consistency" that can be a crutch, preventing deeper understanding. He advises against relying on simplistic rules like "never abbreviate" and instead promotes a more nuanced approach. This involves understanding the 'essence' of an entity, considering its context, potential symmetries with other concepts (e.g., `src` and `dst`), and its implications for future readers. This form of "intellectual empathy" is presented as the true virtue, demanding active thought rather than passive adherence to rules.

Practical examples demonstrate the principle of naming by essence. The distinction between `created_at` and `uploaded_at` illustrates how names must capture the specific meaning and origin of data, especially when dealing with domain-specific versus system-internal objects. Similarly, a function like `mergeTargetValuesIntoSourceTemplate` is criticized for being named after its immediate application rather than its fundamental operation (map union). Such names obscure generality and hinder discoverability and trust, reinforcing the idea that names should communicate fundamental intent rather than transient utility.

The article concludes that the quality of names is intrinsically linked to the quality and maintainability of the codebase itself. The proliferation of code often stems from existing names that fail to capture underlying concepts or generalize effectively. By focusing on naming as an act of clear communication and deep understanding, developers can not only improve their own thinking but also create systems that are more robust, understandable, and adaptable to future needs and tools, including AI.

Tech

Covered by: reddit_programming

How to name things

AI Signal Decode

Related Stories