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

201–210 of 212 posts

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

#201

Post by mgaunard »

panstromek wrote: post #159
mgaunard wrote: post #94

Earlier quoted context omitted.

Fork it, you should have ownership of your whole stack. If you have the spare time, you can try and submit your patches upstream; in the meantime, you just maintain your own version.

No, you can't always do that. We have workarounds for platform bugs that were even fixed, because we get users with old devices that can't upgrade. You cannot fork a phone of a random person on the other side of the world. Once a platform bug is out, it can stay out in the wild for a very long time.

Deploy your own platform -- if need be built on top of other (unreliable) platforms.

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

#202

Post by 8note »

peheje wrote: post #151
tetha wrote: post #141

Earlier quoted context omitted.

This however misses an important point: 3 is not in our control. 3 in general is controlled by math-people, and that 3 in particular is probably in the hands of a legal/regulation department. That's a much more important information to highlight. For example, at my last job, we shoved all constants managed by the balancing teams into a static class called BalancingTeam, to make it obvious that these values are not in…

I like the idea of using a LegalConstants namespace or Code Owners to signal that we don't own those values. However, I’d argue that being 'out of our control' is actually the main reason to test them. We treat these as acceptance tests. The goal isn't flexibility, it is safety. If a PR changes a regulated value, the test failure acts as a tripwire. It forces us to confirm with the PM (and the Jira ticket) that the c…

or very concretely, if legal sets a constant to 0, there should be some test that makes sure the code handles divisions by that number properly, or otherwise fail to deploy.

youd need tests both with the current constant for the current state, and with various bounds on that constant to show that the code always works

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

#203

Post by 8note »

sbuttgereit wrote: post #138
peheje wrote: post #130

Earlier quoted context omitted.

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.…

Until someone changes the test to be four days, or two, but doesn't update the test name. Ultimately disciplined practice requirements rely on disciplined practices to succeed. You can move the place where the diligence needs to taken, but at the end the idea that comments can lose their meaning isn't that different to other non-functional, communicative elements also being subject to neglect. I don't mean to suggest…

with code in good shape, i think i prefer having unnamed tests and instead you read the test to see that its an important function.

however, ive also done code archaeology, and same thing, old inaccurate comments were one of the few remaining things with any idea what the code was supposed to do and got me enough pointers to company external docs to figure out the right stuff.

wiki links, issue links, etc all had been deleted. same with the commit history, and the tests hadnt worked in >5 years and had also been deleted

the best comments on that code were about describing Todos and bugs that existed rather than what the code did do. stream of consciousness comments and jokes

what Ive left for future archaeologists of my code is detailed error messages about what went wrong and what somebody needs to do to fix that error

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

#204

Post by 8note »

zahlman wrote: post #177
bluecalm wrote: post #134

Earlier quoted context omitted.

It's like with goto. Goto is useful and readable in quite a few situations but people will write arrow like if/else tree with 8 levels of indentation just to avoid it because someone somewhere said goto is evil.

Funny how my Python code doesn't have those arrow issues. In C code, I understand some standard idioms, but I haven't really ever seen a goto I liked. (Those few people who are trying to outsmart the compiler would make a better impression on me by just showing the assembly.) IMX, people mainly defend goto in C because of memory management and other forms of resource-acquisition/cleanup problems. But really it comes…

> if (!b) { cleanup_a(a); return -2; }

this rings alarm bells for me reading that a cleanup_c(c) has maybe been forgotten somewhere, since the happy and unhappy paths clean up different amounts of things.

i imagine your python code escapes the giant tree by using exceptions though? that skips it by renaming and restructuring the goto, rather than leaving out the ability to jump to a common error handling spot

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

#205

Post by 8note »

frumiousirc wrote: post #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 m…

the first time you write something, descriptive names are handy, but if youre writing a second or thrid copy, or trying to combine several back down into one, those names are all baggage and come with a full mental model.

an alternative ive seen work well is names that arent descriptive on their own, but are unique and memorable, and can be looked up from a dictionary

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

#206

Post by 8note »

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…

you can get a few more anchors in with a builder:

   aerodynamicDrag(DragInput.builder()
        .dragCoefficient(quadConfig.dragCoefficient), 
        .speed(v3.length(quadVel))
        .referenceArea(quadConfig.frontalArea)
        .build()
    )
which i think points at a possible bug where there drag coefficient isnt measured for the frontal area and needs to be rescaled?

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

#207

Post by zahlman »

8note wrote: post #204
zahlman wrote: post #177

Earlier quoted context omitted.

Funny how my Python code doesn't have those arrow issues. In C code, I understand some standard idioms, but I haven't really ever seen a goto I liked. (Those few people who are trying to outsmart the compiler would make a better impression on me by just showing the assembly.) IMX, people mainly defend goto in C because of memory management and other forms of resource-acquisition/cleanup problems. But really it comes…

> if (!b) { cleanup_a(a); return -2; } this rings alarm bells for me reading that a cleanup_c(c) has maybe been forgotten somewhere, since the happy and unhappy paths clean up different amounts of things. i imagine your python code escapes the giant tree by using exceptions though? that skips it by renaming and restructuring the goto, rather than leaving out the ability to jump to a common error handling spot

> this rings alarm bells for me reading that a cleanup_c(c) has maybe been forgotten somewhere, since the happy and unhappy paths clean up different amounts of things.

The exact point of taking the main work to a separate function is so that you can see all the paths right there. Of course there is no `c` to worry about; the wrapper is so short that it doesn't have room for that to have happened.

The Python code doesn't have to deal with stuff like this because it has higher-level constructs like context managers, and because there's garbage collection.

    def get_resources_and_do(action):
        with get_a() as a, get_b() as b:
            action(a, b)

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

#208

Post by panstromek »

mgaunard wrote: post #201
panstromek wrote: post #159

Earlier quoted context omitted.

No, you can't always do that. We have workarounds for platform bugs that were even fixed, because we get users with old devices that can't upgrade. You cannot fork a phone of a random person on the other side of the world. Once a platform bug is out, it can stay out in the wild for a very long time.

Deploy your own platform -- if need be built on top of other (unreliable) platforms.

Our website codebase contains a workaround for a bug in native Android file picker in Samsung One UI. How are you supposed to solve this by "deploying your own platform?"

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

#209

Post by mgaunard »

panstromek wrote: post #208
mgaunard wrote: post #201

Earlier quoted context omitted.

Deploy your own platform -- if need be built on top of other (unreliable) platforms.

Our website codebase contains a workaround for a bug in native Android file picker in Samsung One UI. How are you supposed to solve this by "deploying your own platform?"

By decoupling your application logic from your UI toolkit.

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

#210

Post by panstromek »

mgaunard wrote: post #209
panstromek wrote: post #208

Earlier quoted context omitted.

Our website codebase contains a workaround for a bug in native Android file picker in Samsung One UI. How are you supposed to solve this by "deploying your own platform?"

By decoupling your application logic from your UI toolkit.

So, when operating system gives you invalid file, it magically becomes valid, because your UI code is in a different file. Sure, that sounds plausible.
Post reply on HN