Live data from Hacker News

Maybe comments should explain 'what' (2017)

hillelwayne.com

11–20 of 212 posts

Re: Maybe comments should explain 'what' (2017)

#12
post #2

I feel like no one serious uses the uncle Bob style of programming anymore (where each line is extracted into its own method). This was a thing for a while but anyone who's tried to fix bugs in a codebase like that knows exactly what this article is talking about. It's a constant frustration of pressing the "go to definition" key over and over, and going back and forth between separate pieces that run in sequence. I…

> where each line is extracted into its own method

Never heard of "that style of programming" before, and I certainly know that Uncle Bob never adviced people to break down their programs so each line has it's own method/function. Are you perhaps mixing this with someone else?

Re: Maybe comments should explain 'what' (2017)

#13
Should stick a (2017) on there as this is almost a decade old.

Comments should explain. If it’s why, it’s why. If it’s what, it’s what. The point of comments is to explain, to the reader/editor, what the intent of the code is and how you chose to approach it. That’s it. No need to fight over what, why, how, who, etc.

If you have domain knowledge that helps support the code, maybe a link to further reading, by all means add it to comments please!

Re: Maybe comments should explain 'what' (2017)

#15
post #7

Isn’t the purpose of comments to make code understandable? If that needs a why it’s a why-comment. If it needs a what it’s a what-comment. Especially if clever programming tricks are used. 6 month later you already forgot what the trick is and how it works.

Yes, but some people have a Jihad against "what" comments - believing these should be elevated into the structure of the code itself, eg veryVerbosePainfullySpelledOutVariableNames or thisFunctionNameExplainsAWholeDomainConcept()

Re: Maybe comments should explain 'what' (2017)

#16
The article is about comments. But, more generally, I think the issue here is about naming things.

Names capture ideas. Only if we name something can we (or at least I) reason about it. The more clear and descriptive a name for something is, the less cognitive load is required to include the thing in that reasoning.

TFA's example that "weight" is a better variable name than "w" is because "weight" immediately has a meaning while use of "w" requires me to carry around the cumbersome "w is weight" whenever I see or think about "w".

Function names serve the same purpose as variable names but for operations instead of data.

Of course, with naming, context matters and defining functions adds lines of code which adds complexity. As does defining overly verbose variable names: "the_weight_of_the_red_ball" instead of "weight". So, some balance that takes into account the context is needed and perhaps there is some art in finding that balance.

Comments, then, provide a useful intermediate on a spectrum between function-heavy "Uncle Bob" style and function-less "stream of consciousness" style.

Re: Maybe comments should explain 'what' (2017)

#17
I'm all against commenting gatekeeping. IMO this is an anti-pattern.

Even in stupidest cases, like:

    // add two and two
    let four = two + two
The rationale for this is that if you start to mute developer on case of "this is not comment-worthy" you start to actually losing context for the codebase. Sure, maybe "add two and two" is not contextful enough, but "add same account twice" might be signal for appropriate code.

Maybe that's me, but I rarely saw teams which over-document, under-documenting is usually the case. So if we ever meet in professional environment - comment away. Worst case scenario - I'll skim over it.

Re: Maybe comments should explain 'what' (2017)

#19
Here's a thought, and I'm just spitballin' here: maybe they could do both? Sure, writing an encyclopedic tome about three lines of code is probably a bit out of bounds, but overexplaining is only bad when it's your wife or girlfriend. It might be a good idea to be absolutely clear about things.
Post reply on HN