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

51–60 of 212 posts

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

#51

Post by panstromek »

xlii wrote: post #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.

This is a good point, although this recently changed with LLMs, which often spit out a ton of redundant comments by default.

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

#53

Post by broken-kebab »

IMO the example shows exactly that splitting code in smaller pieces is way better than just commenting it.

It makes it easier for dev's brain to parse the code e.g. to understand what code really does, while fattier but commented version makes it harder but tries to replace it with information about original coder's intentions. Which is maybe important too but not as important as code itself.

Not to forget that it's too easy to change code and leave comments obsolete.

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

#54

Post by dijksterhuis »

jackfranklyn wrote: post #10

[flagged]

ime summaries/details of the “business what” are the most important part of “why the code exists/is written this way” — it’s the overarching problem that section of code aims to solve / needs to work around!

they can also be a good defence against newer seniors on the team refactoring willy nilly — can’t argue with business rules, but can argue over uncle bob. ;)

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

#55

Post by mashally »

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”

I agree with that as well, the "why" explains the business logic and that makes much more sense to me. Otherwise, I might end up explaining the algorithm (the "what") instead of the business behind it.

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

#56

Post by __s »

Scarblac wrote: post #23
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…

Turns out writing a book and getting it published with the title "Clean Code" is great marketing. I have had so many discussions about that style where I tried to argue it wasn't actually simpler and the other side just pointed at the book.

Cult think loves a tome

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

#57

Post by dijksterhuis »

tetha wrote: post #50
jackfranklyn wrote: post #10

[flagged]

> That's explaining "what" but also implicitly "why" - because that's how double-entry works and that's the tolerance banks allow for settlement delays. You can't really extract that into a method name without it becoming absurd. That's why I've also started to explicitly decompose constants if possible. Something like `ageAlertThresholdHours = backupIntervalHours + approxBackupDurationHours + wiggleRoomHours`. Sure,…

i personally prefer this kind of version — if i want to do the maths to work out tweaks i can, but i’m not forced to do maths in my head to know/tweak the end value

    // a total of 
    // - backup interval = 24
    // - approx backup duration = 2
    // - “wiggle room” = 2
    ageAlertThresholdHours = 28
yes lazy devs are lazy and won’t want to or just won’t update the comments (be pedantic in review :shrug:). it’s all trading one thing off with another at the end of the day.

edit — also your version forces me to read horizontal rather than vertical, which takes longer ime.

sorry, i’ve basically done an unprompted code review. i feel like a bit of a dick now.

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

#58

Post by mattacular »

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, anything your human brain can think of will probably be more helpful context.

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

#59

Post by chuckadams »

panstromek wrote: post #51
xlii wrote: post #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. This is a good point, although this recently changed with LLMs, which often spit out a ton of redundant comments by default.

Claude Code in particular seems to use very few redundant comments. That or it's just better at obeying the standing instruction I give it to not create them, something other assistants seem to blithely ignore.

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

#60

Post by boredemployee »

epolanski wrote: post #37

I like antirez' style of comments. He starts implementing any module or function by first writing the documentation for it and let's it guide both the functionality and structure. Makes Redis also extremely easy and enjoyable to read. Random example: https://github.com/redis/redis/blob/unstable/src/aof.c

Really nice, we would have a better world if comments like that were the standard.
Post reply on HN