Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Maybe comments should explain 'what' (2017)

hillelwayne.com

Post reply on HN
Print view View original

71–80 of 212 posts

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

#71

Post by WillAdams »

awesan wrote: 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…

For an example of what happens when he runs into a real programmer see:

https://github.com/johnousterhout/aposd-vs-clean-code

_A Philosophy of Software Design_ is an amazing and under-rated book:

https://www.goodreads.com/en/book/show/39996759-a-philosophy...

and one which I highly recommend and which markedly improved my code --- the other book made me question my boss's competence when it showed up on his desk, but then it was placed under a monitor as a riser which reflected his opinion of it....

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

#72

Post by 3371 »

mattacular wrote: post #58

Explain "why not what" is good general advice. My further advice for comments is: even bad comments can be useful (unless they're from LLM output maybe...) therefore when in doubt, write a comment. Write it in your own words. Had to add the last sentence for the circa 2020s developer experience. LLM comments are almost never useful since they're supposed to convey meaningful information to another human coder, anythi…

I always think LLM comments are more about helping themselves to stay on track.

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

#74

Post by CuriouslyC »

mattacular wrote: post #58

Explain "why not what" is good general advice. My further advice for comments is: even bad comments can be useful (unless they're from LLM output maybe...) therefore when in doubt, write a comment. Write it in your own words. Had to add the last sentence for the circa 2020s developer experience. LLM comments are almost never useful since they're supposed to convey meaningful information to another human coder, anythi…

AI comments are fine for high level summaries of the what/how. They fail at the why, which is where we come in.

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

#75

Post by okonomiyaki3000 »

We need to differentiate between a "What this is" comment and a "What this does" comment. "What this does" is a lot closer to "Why" than it is to "What this is". I would hope "What this is" is rarely needed but "What this does" can certainly be helpful pretty often.

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

#77

Post by bostik »

coffeebeqn wrote: post #11
jackfranklyn wrote: post #10

[flagged]

I also do that but I’d argue that business rules/quirks count as a “why”

While I agree, I think that's still incomplete. To me good comments have always been about "what is being done AND why".

Or to put it another way: to provide the necessary context for figuring out why a particular piece of code is written the way it's done. (Or what it's supposed to do.)

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

#78

Post by CuriouslyC »

zero_shift wrote: post #6

Sometimes I want to use comments because I'm doing something vaguely algorithmic, and I know some readers won't follow the code. I'm trying to think of a good example, maybe something like a pointer window based function (off the top of my head) (This isn't real code. Don't get hung up on it) func DedupeStrings(ss []string) []string { if len(ss) People will quibble, but - I'm not convinced you could change the variab…

What is ss supposed to mean? Also, I only know what "u" means because of your "uniques" comment.

Those comments also don't really help me quickly understand the code. I'd do a small doc comment along the lines of "Removes repeated elements from the supplied list, returning the remaining items in original order"

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

#80

Post by Scarblac »

croes wrote: post #38
Scarblac wrote: post #29

Earlier quoted context omitted.

Yes, but there are other ways to make it more understandable (like good names, idiomatic code, units that are neither too long nor too short) that are often preferable, because comments always have a danger of going out of sync with the code. The "why" is the part of the explanation that can't be deduced from the code.

Sometimes good names etc. don’t help. Think of this https://en.wikipedia.org/wiki/Fast_inverse_square_root That definitely needs a what comment.

Yes of course, sometimes there is no understandable way to write the code and comments are the best way.

But there's also the case to be made that the comments that particular code needs are "why" comments. I can see what happens, but why does it work?

Post reply on HN