Of course comments stay in sync with the code... if you're the only one working on that code. As soon as you have multiple developers, you can forget about it.
If I am in a rush to implement something and then am sidetracked because of a stupid small bug, then I just fix that small bug in the code. And then another one. In these states I only pay attention to code, and not text. If I would also have to read the text, then I would forget the original task.
So sadly no, comments do not automatically stay in sync with code for me, unless I put in the extra effort of cleaning up afterwards.
What if the small bug that side-tracked you eould have been prevented by a comment?
But seriously, in the cases I remember - not really. Most bugs are a cause of lack of higher level understanding of a certain module. Some clear comments can help with that, but better is proper higher level documentation and the time to read and maintain them.
Agreed. However I've found that the farther away the documentation is, the less people will use it.
If it's external, it's very hard to get people to use it.
Slow down, it'll get done faster.
And you are free to be as slow as you want, but my flow state works a bit different and context switches are expensive. Which is why I want the minimum of comments and rather have self explaining code and proper higher level documentation.
That's only true if everyone can check in code willy-nilly without any approval.
If you require code reviews then that's just part of the code review. No documentation update = no approval, just like missing tests or bad code.