Comment by shawnz
12 hours ago
If you are only encoding intent through "self-documenting code", and not with comments, then you are purposefully not using all the tools at your disposal to encode meaning as efficiently as possible.
Imagine a complicated section of application logic. You could break it up into 5 separate functions that document their intent semantically, thus blowing up the LOC by 5x, or you could write a short comment explaining the intent in natural language. What's more effective? I'd argue it's always going to be using all the tools at your disposal when and where it makes sense to use them, whether that is comments or self-documenting code.
> You could break it up into 5 separate functions that document their intent semantically, thus blowing up the LOC by 5x
I do this all the time and the "blowup" is not anywhere near that bad.
> or you could write a short comment explaining the intent in natural language.
You really can't. Or rather, you aren't going to convey the information that the new function signatures convey, shorter than the signatures themselves.
> What's more effective?
In my literal dozens of years of experience, the function refactoring. You also get the benefits of less deeply nested code, and more things the compiler can check automatically.
> I'd argue it's always going to be using all the tools at your disposal when and where it makes sense to use them, whether that is comments or self-documenting code.
Sure. Comments allow you, for example, to explain the external pressures and motivations for the semantics of those smaller functions.
Not to mention complex numerical optimization code that mixes closed-form approximations and something like Newton.
Without guides as to why a particular hairy expression is a good idea as a first estimate, the code is pretty much unreadable. (E.g. is it setting derivatives to zero, using a polynomial approximation, or something else?)
i think people took this too literally.
To put it another way, comments are for irreducible complexity ir external systems outside your control.
I work between systems and app dev. Systems have comments more often esp in shaders but my god informing me that a variable named isActive is for if something is…active, is useless noise. Same with the majority of comments that a type system already tells you. In my career, these have been ~90% of the comments I see. Since ai, all new code it is 100%.
Most of the replies examples are a sign of bad system/code but it is not always controllable. A legacy code comment of, the api requires strings for boolean values in the form “yes” and “no”. That is useful but it is also a code smell.
A concrete example, a vendor decided to define a proto with a flattened array of objects so there are some 1800 uniquely named fields on it. In many downstream consumers, this is a real performance issue besides being confusing. A comment may be good there. The thing is, this was still solvable if up at the root of where this vendor’s hardware logs data remapped it to something sane so every downstream system wouldnt need a comment explaining wtf is going on.
I see comments as when you want to explicitly answer why code smells right when a reader is smelling it.