If the explanation is directly connected to specific parts of the code, it's not "why", it's "how". "Why" will be true regardless of implementation, "how" won't be.
Comments should be less visible, as they distract the coder from understanding what the code actually does with potential lies about what the code ought to do, according to the flawed human who wrote the code.
Put the comments elsewhere. 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, it is not consistent nor is it helpful.
> 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're treating comments like a pariah because they might be wrong (i.e. not accurately describe what the code is doing) but that's just as true for the code itself: it may not be doing what it is actually intended to do.
In fact, there may be cases where the comment is correct (i.e. it describes what the code should do) but the code is wrong and doesn't actually do it correctly. Why should the comments take a back seat in that case?
In reality, comments and code are part of the whole system. There's nothing wrong with being suspicious of a comment's accuracy, but that doesn't mean comments aren't helpful. Part of development is keeping code and comments in sync. Yes, programming is hard.
This is a bad take, as the code is actually executed, whereas comments are not.
As the code is, definitionally, the way the program works, it must be correct, necessarily. This is not true of the comments.
This is why comments are dangerous and bad, only to be used when you've run out of time and/or aren't smart enough to figure a problem out (happens to everyone).
I respectfully disagree with your assertion that because the code is how the program works, it is by definition correct. Wouldn't you define a bug as incorrect code?
In any case, even if the code is perfectly correct, comments can and should be used to describe why certain decisions were made, when they are not otherwise obvious from looking at the code. E.g. "You might think a bitfield would be more efficient for storing this data but we choose an array of long ints because in the near future we plan to update the code to pass this as an argument to foo() which assumes an array of long ints."
Comments are not limited to instances when you run out of time or are not smart enough to figure out a problem. The whole idea of comments is to save a future developer from the headache of figuring out the things you're writing comments about.
Comments should be less visible, as they distract the coder from understanding what the code actually does with potential lies about what the code ought to do, according to the flawed human who wrote the code.
Put the comments elsewhere. 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, it is not consistent nor is it helpful.