re: Coding practices your future self will love you for VIEW POST

TOP OF THREAD FULL DISCUSSION
re: The only trouble with deciding whether a comment is "useful" or not while you code is that, during the process, everything you do seems obvious. Th...

I just realized (and this isn't aimed at any particular person here), but I think that from a psychological perspective, one reason people seem to be so uncomfortable with the idea of commenting intent traces back to imposter syndrome...

There are those coders who write "clever" code that the average programmer is simply awestruck by. Even when it's completely "clean", the cerebral nature of the code is just too incomprehensible to any but the most senior developers...yet nothing particularly clever is actually being accomplished. The developer in question is trying to be Mel, and the moment they actually admit what the intent ("why") of their code is..."Oh, I'm just searching for a value in an array"...the smoke is cleared away, exposing their Cleverness as mere Overengineering.

I'm far from suggesting this is a common reason for opposing intent-commenting, but I have no doubt it is one of the reasons.

On a broader scale, however, I think it isn't unreasonable to assume that there are plenty of coders who naturally fear code critique by their peers, and if they're entirely up-front about their intent, they'll be subject to feedback along the lines of "Why are you doing this the hard way?"

By keeping our intent to ourselves, we feel like we can hide behind our (otherwise clean) code. Most of our peers won't bother to read it in light of what it's intended to be doing, so we're more likely to get "LGTM" code reviews and glaze-eyed pats on the back. Intent commenting exposes our inner thought processes to the open source world for public scrutiny, and I think that scares the Dickens out of a lot of people.

Yes. Emphasis on adding value. Repeating code in English (or another human language) is one of my pet peeves, but if it adds value, then I'm for that.

Precisely! Intent-comments only work if they add value: a clear expression of the intention apart from the code itself.

That's one of the major reasons I wrote the standard: to differentiate between junk comments and useful ones, and to encourage the latter.

+1 for mention of Mel

I feel my future self will disown any gratuitous 'cleverness', so for me personally, a comment on some clever code is more likely to be an admission to Future Self of being too much clever, and not enough smart :-)

Also, it's a little like explaining the punch line of a joke. One either feels that the joke has failed, or else being condescending to explain it. Another form of imposter syndrome

code of conduct - report abuse