This seems to be a contentious subject, at least with the few people I’ve spoken to… and I seem to be on the “losing side” as it were…
I can certainly see both sides of argument, however, for me at least, I comment the hell out of my code! The reason I do this is twofold;
Firstly, my memory is terrible… I don’t mean Momento-esque… I can actually remember who I am and most of the time, what I did yesterday… But, give me more than a few days, and I’ve forgotten the meaning of what I’ve written (along what I’ve done and sometimes who I am… But that’s another story… Hahaha).
That is, I can understand the code – Any decent programmer could – But… “Why have I done that in that order?” and “Why have I needed to call that particular function before I continue on with my code?” – It’s easy for me to forget the story… The plot if you will.
So, I write comments to remind my future self of the story of my code… Perhaps how it evolved… That is… “We perform this function here because it causes stack overflow issues if we do it during x”, or… “there’s a bug in x dll that means we have to work around it by doing this…”, So it’s a narration almost…
Secondly (and perhaps most importantly for me); I’ve consulted for enough companies, where I’ve taken on someone else’s code and looked at it and said to myself “what the hell is this actually trying to do?”. So I write my comments as if a random new developer is coming to this code fresh, with no experience of the platform at all.
The way I explain this point is with a (stupid I grant you) analogy…. Imagine that you took the idea of “the code should comment itself” quite literally… Only, you were a top programmer working for NASA. Whatever you write, might make perfect sense to the top 1% who you are expecting to be employed by NASA. However, this code is total gibberish to the rest of us 99% “normal” people.
This final point seems to illustrate my thinking most of all to be fair. “The code should comment itself” seems to be the mantra and in fact, I actually agree; Write your code as clearly as possible… instead of writing “idx” write “QualityControlItemId” , instead of “counter”, write “numberOfItemsRequired”. Comment the seemingly “random” way you’ve written your code because it “seems to work” with an explanation as to why you’ve done that!
Self documenting code is fine, if the person you expect to be reading that documentation is your clone… Right now… With your head clear and fully in the game with no distractions, and with exactly the same understanding of the subject material as you have. If you expect anything other than that, then I choose to leave myself a breadcrumb trail at least, if not that, a full bloomin’ novel explaining my thinking in that fleeting moment between that piece of code and the next…
For me at least, writing comments is like writing tests… Yes, they take time to write, and yes, they take time to maintain… But heck… They save me a load of time in a years’ time – When I’ve forgotten most of what I’ve done and why I’ve written it that way – For that alone, the short term pain is well worth the long term gain!