Rethinking Programming Advice: The Case for Comments That Explain 'What'
By
zahrevsky
Hand-rolled, kettle-boiled, baked to perfection. Worth every minute at the bakery.
Summary
The article challenges the common programming advice that "comments should explain why, not what." The author argues that comments explaining 'what' can be valuable, especially when code isn't immediately clear or when dealing with complex logic. They provide examples showing how explanatory comments can improve understanding, particularly for beginners or when revisiting code later. The piece acknowledges that clear code should be the goal but contends that 'what' comments serve as useful documentation and learning aids.
Key quotes
· 4 pulledPeople say 'Comments should explain why, not what.' I feel like starting a flame war today so I'm going to argue that comments should explain 'what' too.
First of all, why shouldn't comments explain 'what'? If you need comments to explain what's going on, it suggests your code is unclear.
That's not as clear as saying weight = 10, radius = 9, price = 3
But it's obvious that w is weight! Sure, if you're seeing those lines back-to-back.
You might also wanna read
Why Average LLM Use Is Likely Destroying Value in Software Development
The author argues that, contrary to prevailing hype, the average use of Large Language Models (LLMs) is likely destroying value rather than
unessays.substack.com·10h ago
How AI Accelerated Prototyping: From Idea to Tangible in Record Time
The author reflects on how AI has transformed their prototyping workflow. Previously, the biggest bottleneck was the time needed to scaffold
darylcecile.net·10h ago
GitLab 19.0 launches with Secrets Manager, agentic workflows, and self-hosted AI models
GitLab 19.0 has been released, positioning itself as an intelligent orchestration platform for DevSecOps. The release includes expanded secr
bit.ly·23h ago
Centralizing Error Handling in Rust with Custom AppError Enums
This article discusses the importance of centralizing error handling in Rust applications using a custom AppError enum combined with map_err
Zig Devlog: Build System Rework Separates Maker and Configurer Processes
This devlog entry from the Zig programming language project announces a major rework of the build system, separating the maker process from
ziglang.org·1d ago
Study finds most developers refuse to code without AI, raising quality concerns
A February 2026 study by AI research lab METR reveals that most developers now refuse to work without AI coding tools. While these tools hel
techcrunch.com·1d ago