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

121–130 of 212 posts

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

#121

Post by hamdingers »

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.

> and the other side just pointed at the book

One of the most infuriating categories of engineers to work with is the one who's always citing books in code review. It's effectively effort amplification as a defense mechanism, now instead of having a discussion with you I have to go read a book first. No thanks.

I do not give a shit that this practice is in a book written by some well respected whoever, if you can't explain why you think it applies here then I'm not going to approve your PR.

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

#122

Post by TZubiri »

The maybe is the strongest part of this article.

In my early days I read a lot of "you should" "this is wrong". But code is an expressive medium, you can do things one way, or do it the other, you can write "amountOfEmployees" or you can write "ne" with an "#amount of employees" comment, either way is absolutely fine and you can use whichever depending on your priorities, tradeoffs or even your mood.

Also I used to obsess over code, (and there's a lot of material that obsesses about code), but after you become profficient at it, there's a cap on the returns of investing time into your codebase, and you start to focus on the product itself. There's not much difference between a good codebase and a marvelously polished codebase, so you might as well use the extra focuse on going from a bad UX to a neutral UX or whatever improvement you can make to the product.

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

#123

Post by TZubiri »

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…

It's an extremism to get a strong reaction, but the takeaway is that you should aim when possible to make the code understandable without comments, and that a good programmer can make code more understandable than a newbie with comments.

But of course understandeable code with comments simply has much more bandwidth of expression so it will get the best of both worlds.

I see writing commentless code like practicing playing piano only with your left hand, it's a showoff and you can get fascinatingly close to the original piece (See Godowsky's Chopin adaptations for the left hand), but of course when you are done showing off, you will play with both hands.

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

#124

Post by TZubiri »

ivanjermakov wrote: post #108

I noticed that when I write code that is not trivial to understand I tend to extract intermediate values into variables with meaningful names. applyDrag(): void { const { quad: quadConfig } = settings const quad = this.getRigidBody() const quadVel = vec3ToTwgl(quad.linvel()) const dragMag = aerodynamicDrag(quadConfig.dragCoefficient, v3.length(quadVel), quadConfig.frontalArea) const dragDir = v3.negate(v3.normalize(q…

Funny how even in this very verbose code (which is perfectly fine btw), there's still a need to use shorthands (quadVel). It's like completely explained code requires so many words, but we need to fit the code into a certain character window.

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

#125

Post by commandersaki »

filoeleven wrote: post #110

The bigger point I take from this is that the purpose of comments and good names are all attempts to help the developer grasp "the context of this code". The article uses "context switch" repeatedly, and in fact never uses the word "context" any other way. Since the author acknowledged they're starting a friendly flame war, I'll go ahead and add that the biggest problem with the example code is that it's object-orien…

The translation from function to class Martin Bob style makes it become literal spaghetti code.

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

#126

Post by croes »

Scarblac wrote: post #80
croes wrote: post #38

Earlier quoted context omitted.

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?

Why does it work or why was the code written?

The article mentions the reason for the code which I would expect in the commit message

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

#127

Post by drob518 »

I agree with the OP, but, unfortunately, posts like this generate more heat than light. Like a lot of things, what and how to comment code comes down to “do the right thing,” not a list of rules, where everyone will always find counter examples. Do whatever you need to communicate effectively with “the next guy,” who could very well be you.

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

#128

Post by scottlamb »

shiandow wrote: post #114
scottlamb wrote: post #111

This is tangential to the article's point, but that `replace` function is a complete WTF in a way both authors completely ignore. Because it replaces things in the entire string in a loop, it will translate symbols recursively or not depending on ordering. Imagine you have the following dictionary: a=$b b=oops if your input string just has one of these, it will just be translated once as the programmer was probably e…

The insane thing to do would be to implement a variant of loeb so it works regardless of order.

That'd still be less surprising!

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

#129

Post by seba_dos1 »

lukan wrote: post #118
epgui wrote: post #99

Earlier quoted context omitted.

What you describe really is describing the "why", not the "what". The line between the two is not that blurry: assume your reader has total knowledge of programming, and no knowledge whatsoever of the outside world. Comments about what the code does to bits are the "what"; comments about how the code relates to the outside world are the "why". The rest is a matter of taste and judgment.

Just curious, you advice against "what" comments? "assume your reader has total knowledge of programming" Because if I know my fellow programmers have like me not a total knowledge of programming, what comments before footguns seem useful to me. Or when there was a hack that is not obvious. To me it mostly is not a question of taste, but context. Who will read the code?

If you're writing a coding tutorial, you'll want to comment on the "what" indeed. Otherwise it will most likely end up being more distracting than useful, and sometimes even misleading. Exceptions exist, but by virtue of being exceptions there's no catch-all rule for them, so just use your judgment.

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

#130

Post by peheje »

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 don't necessarily disagree with providing context, but my concern is that comments eventually lie. If the business rule evolves (say the window moves to 5 days) the comment becomes a liability the moment someone updates the code but forgets the prose.

The comment also leaves me with more questions: how do you handle multiple identical amounts in that window? I would still have to read the implementation to be sure.

I would prefer encoding this in an Uncle Bob style test. It acts as living documentation that cannot get out of sync with the code and explains the why through execution. For example:

  test("should_match_debit_with_credit_only_if_within_three_day_settlement_window", () => {
      const debit = A_Transaction().withAmount(500.00).asDebit().on(JANUARY_1);
      const creditWithinWindow = A_Transaction().withAmount(500.00).asCredit().on(JANUARY_4);
      const creditOutsideWindow = A_Transaction().withAmount(500.00).asCredit().on(JANUARY_5);
  
      expect(Reconciliation.tryMatch(debit, creditWithinWindow)).isSuccessful();
      expect(Reconciliation.tryMatch(debit, creditOutsideWindow)).hasFailed();
  });
This way, the 3 day rule is a hard requirement that fails the build if broken rather than a suggestion in a comment block.
Post reply on HN