Hillel Wayne Advocates for 'What' Comments in Code

Software engineer Hillel Wayne has published a new article arguing for a specific approach to code commenting. The central thesis is that comments should primarily explain what a piece of code is doing and why it is necessary, rather than explaining how it works. Wayne suggests that the 'how' is usually self-evident from reading the code itself, especially with modern, readable syntax.

The article references historical software engineering standards, specifically those used by NATO in the 1970s. These standards required that every function include a header comment explaining its purpose and interface. Wayne posits that this discipline helps maintain code clarity and reduces the cognitive load on future developers who must maintain the system. The discussion highlights a common debate in software development regarding documentation practices and code maintainability.

The core argument presented by Hillel Wayne centers on the distinction between explaining the mechanics of code versus its intent. Wayne argues that modern programming languages are often expressive enough that the implementation details, or the how, are visible simply by reading the code. Therefore, dedicating comment space to explaining the mechanics is redundant and can often become outdated as the code evolves.

Instead, the author advocates for comments that describe the what—the specific action the code is taking—and the why—the business logic or reasoning behind that action. This approach is intended to provide context that cannot be inferred from syntax alone. By focusing on intent, developers can better understand the purpose of a function without needing to mentally parse every line of logic.

To support this viewpoint, the article looks back at established software engineering practices from the past. Specifically, it references standards utilized by the NATO (North Atlantic Treaty Organization) software development groups in the 1970s. These rigorous standards were designed to ensure reliability and clarity in complex software systems.

According to the referenced standards, every function was required to have a header comment. This comment was not meant to describe the internal logic line-by-line, but rather to explicitly state the function's purpose and its interface. This historical example serves as a validation for the idea that separating the 'what' from the 'how' in documentation is a long-standing best practice for maintaining high-quality code.

Wayne's argument touches on a broader conversation within the Y Combinator community and the wider tech industry regarding code maintainability. As software systems grow in complexity, the ability for new developers to quickly grasp the intent of existing code becomes critical. Relying solely on variable names and function signatures often leaves gaps in understanding regarding the architectural decisions made previously.

By adopting a comment style that focuses on explaining the 'what' and 'why', teams can create a more durable knowledge base. This practice helps prevent the accumulation of technical debt caused by misunderstood requirements or hidden dependencies. It encourages a discipline where documentation serves as a guide to the system's architecture rather than a redundant transcription of its syntax.

The discussion initiated by Hillel Wayne serves as a reminder of the enduring principles of software engineering. While tools and languages evolve, the fundamental need for clear communication between developers remains constant. The argument for prioritizing 'what' and 'why' comments offers a practical framework for achieving this clarity.

Ultimately, the goal of any commenting strategy is to make code easier to understand and safer to modify. By looking to historical standards like those from NATO and applying them to modern contexts, developers can ensure that their codebases remain accessible and robust for years to come.