Comment Section

[jserrao]

Overall this guide is excellent but you're really going to have to sell me on not commenting code. In my eyes, the code is how but how else do you communicate context - the why of it? I'd like to hear your full argument in this guide somewhere.

[ryanmcdermott]

I think that's a fair critique -- Chapter 4 of Clean Code gives a lot more explanation regarding distinctions between Good comments and Bad comments. After all this time I realize that is a shortcoming of this project that I need to rectify.

[TheThirdRace]

In my experience, "self explaining code" is a dogma that everybody repeats, but very few actually really understand.

This is how it usually goes:

1. A developer believes his code is self explanatory and thus don't comment it
2. A bug arise
3. You open the code and it makes absolutely no sense whatsoever (inits not at the start, operations done in weird order, spaghetti code, etc.)
4. You refactor the whole function WITH comments (see "what" vs "how" below)
5. Now the function works and nobody has troubles modifying the new code (and they do so mostly without bugs!!!)

I personally use comments to leave a trace of "what" I want to accomplish, not "how" I accomplish it. This leaves clear indications to future developers on how to read the function, what's the train of thoughts that compose this process and especially what that process is supposed to be.

I fully agree there are bad comments, but personally, I've very rarely seen these in the wild.

What I do see is the lack of comments and the chaos that follows. That, I see pretty much every day... 😅