Huh, I’d be interested to sit down with someone like that and better understand their viewpoint. I wonder if it’s just comments that describe what the code is doing (“what” not “why”) that they have a problem with and are just throwing the baby out with the bath water.

I’ve written mini-blog posts in comments before to explain a complex system or an odd bit of code that is the result of a massive bug in production that I want to document and explain the reasoning behind it.

Documenting every piece of logic just because, I believe, is a code smell. However, look at Rust's documentation (or public crates, at varying levels), all the documentation is extracted from the code, with internal links and even external links between crates thanks to cargo doc (which I think is many times better than doxygen and what the Java and C# guys use, and let's not talk about the nonexistent alternative for JS/TS). Code examples in Rust docs can be made to reference the actual code in the crate, and the code block can be marked as "it compiles", "it doesn't compile", etc. And the compiler guarantees that's true. A block that doesn't compile is used as an example of incorrect code.

In the Unity game engine, they use docfx, and I heard from one developer that their system is done in a way that the code examples in the documentation import the actual code and the documentation fails a build if the code doesn't compile, similar to Rust.