Why a Codebase Can Be Sparsely Commented and Still Well Documented

The author asks readers when they last consulted a tool's source code to learn how to use it, noting that most people rarely do. Their tool had comments on under ten percent of its lines but shipped with roughly ninety pages of documentation, available offline through a built-in command. The author argues that code serves three readers: its users, its maintainers, and future readers of changes, and that comments mainly serve the latter two while documentation serves users. Their guiding rule is that comments should explain why rather than how, since code that needs lengthy comments may need refactoring, and comments that merely restate code add noise.