I’ve been partying on the same code base for about five years now. I’ve written about 70% of it, but it’s large enough (200k lines or so) that I can’t keep all of its subtleties in my head.
In the last year alone I’d estimate comments written by my past self have saved me dozens of hours of effort tracking down the reason why code was implemented a certain way. A couple times I’ve undertaken some refactoring that would’ve taken hours, only to find 10 minutes into the process a comment to the effect of “don’t try to refactor in that way, for these reasons” and it was correct.
Maybe my memory is just particularly bad. But if the comments are helpful to me, they’d also be helpful to someone else who didn’t write that code.
It does take practice to know when and how to write those comments though.
That's great, and some people are better at writing useful comments than others. Not to detract from what you're saying, but
> But if the comments are helpful to me, they’d also be helpful to someone else who didn’t write that code.
this does not necessarily follow unless you've been extremely thoughtful in how you wrote those comments (which you may very well have been). That is, in fact, the issue most of the time — that comments are written in such a way that they serve to jog the memory of the person who wrote them, but are rarely of general use to anyone else.
Yeah I agree with this notion. After working in very high level and expressive language (with static typing) I found that I could get rid of about 90% or even more of my comments.
But for the rest, it's exactly as you described. There is usually some workaround/shortcut being taken or there is interfacing with an external dependency that does not work as expected. In those cases comments make aware of things that the code doesn't show and can save a looot of time.
In the last year alone I’d estimate comments written by my past self have saved me dozens of hours of effort tracking down the reason why code was implemented a certain way. A couple times I’ve undertaken some refactoring that would’ve taken hours, only to find 10 minutes into the process a comment to the effect of “don’t try to refactor in that way, for these reasons” and it was correct.
Maybe my memory is just particularly bad. But if the comments are helpful to me, they’d also be helpful to someone else who didn’t write that code.
It does take practice to know when and how to write those comments though.