You’re not wrong, it is insane.
I’ve been told by a few developers over my career that “comments are a code smell”. I believe this is well intentioned but ultimately harmful advice.
I’ve been told by a few developers over my career that “comments are a code smell”. I believe this is well intentioned but ultimately harmful advice.
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.
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.