> We don't put all our code in one file to solve "it needs to be visible!" problems, we shouldn't do it with our docs either
You make comparisons without considering the reasons.
We split code up into multiple files because we cannot have 100% of the code on screen either way and huge files tend to be cumbersome. Whole IDE components are built just to show API docs and other parts of the code exactly where and when we need them. With that in mind it makes no sense to have important comments not be visible where and when we need them.
And even if those comments were in a separate file like you suggest you'd still need a comment in the code to make developers aware of the fact an important explanation of some obscure detail exists. If you don't then any change of that code might invalidate the documentation without anyone knowing, and then you're back at square one with lying comments/docs. Comment visibility also means it's visible when it needs to be updated.
I think you’re trapped in this “comments must exist” mindset that’s simply not true or necessary. Every single thing you like about comments can be accomplished with self documenting code and accompanying “why” docs.
There’s simply no need for inline comments anymore, and continuing to use them is admitting you’re not putting the kind of effort you’re capable of into building software.
> Every single thing you like about comments can be accomplished with self documenting code and accompanying “why” docs.
Except being exactly where and when it's needed, with any modern editor being able to hide it for people who don't want it.
You seem to base everything on the assumption that comments are always the worst choice, and that people don't behave like people but always document things the right way no matter how cumbersome or complex that is compared to the obvious way. Seeing things in black and white is usually not the best solution.
> continuing to use them is admitting you’re not putting the kind of effort you’re capable of into building software.
No, and I hope that kind of thinking won't mislead you into believing you are at your peak because you don't write comments.
And all I’ve said is comments are a last resort. Nothing black/white about that, just tired of egos getting in the way of seeing how there are a million ways in practice to avoid comments that people who “like” comments refuse to learn about.
You make comparisons without considering the reasons. We split code up into multiple files because we cannot have 100% of the code on screen either way and huge files tend to be cumbersome. Whole IDE components are built just to show API docs and other parts of the code exactly where and when we need them. With that in mind it makes no sense to have important comments not be visible where and when we need them.
And even if those comments were in a separate file like you suggest you'd still need a comment in the code to make developers aware of the fact an important explanation of some obscure detail exists. If you don't then any change of that code might invalidate the documentation without anyone knowing, and then you're back at square one with lying comments/docs. Comment visibility also means it's visible when it needs to be updated.