Low-level code where you need to initialize array indices to represent certain flags? ~~Absolutely comment the living shit out of that.~~ → See response.
High-level code where you're just plumbing different libraries? Hell no, the code is just as easily readable as a comment.

I do also think that, no matter where you lie in this spectrum, there is always merit to improving code to reduce the need for documentation:

Rather than typing out the specification, write a unit/integration test.
Rather than describing that a function should only be called in a certain way, make it impossible to do it wrongly by modelling this in your type system.
Rather than adding a comment to describe what a block of code does, pull it out into a separate function.
Rather than explaining how a snippet of code works, try to simplify it, so this becomes obvious.

The thing with documentation is that it merely makes it easier to learn about complexity, whereas a code improvement may eliminate this complexity or the need to know about it, because the compiler/test will remember.

This does not mean you should avoid comments like they're actively bad. As many others said, particularly the "why" is not expressable in code. Sometimes, it is also genuinely not possible to clean up a snippet of code enough that it becomes digestable.
But it is still a good idea, when you feel the need to leave a comment that explains something else than the "why", to consider for a moment, if there's not some code improvement you should be doing instead.

[–] [email protected] 4 points 3 months ago (2 children)

Hard disagree on your first point. Name the flags with descriptive name, move this initialisation to a function, and there you go, self-documented and clear code.

[–] [email protected] 3 points 3 months ago

I'm with you but sometimes you don't have the chance in low level. Max you can do is create local variables just so the bits you're XORing are more obvious. And whenever you're working with something where that'd be wasteful and the compiler doesn't rid if it, you're better off with comments (which you need to maintain, ugh)

[–] [email protected] 2 points 3 months ago

Hmm, maybe my opinion is just shit in that regard. I don't code terribly much low-level, so I'm probably overestimating the complexity and underestimating the options for cleaning things up.
That was kind of just a random example, I felt like there were many more cases where low-level code is complex, but I'm probably basing this off of shitty low-level code and forgetting that shitty high-level code isn't exactly a rarity either.

load more comments (23 replies)