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

Writing Well-Documented Code – Learn from Examples

codecatalog.org

Post reply on HN
Print view View original

141–150 of 153 posts

Re: Writing Well-Documented Code – Learn from Examples

#141

Post by nyberg »

pcmoney wrote: post #119
makeitdouble wrote: post #105

More and more I feel these huge comment blocks with the following inline comments sprinkled everywhere should really be a separate documentation file with its own structure where anyone not familiar enough can get up to speed, and understand the core principles behind the code written here. For instance in the firecracker example, they don’t write 3 pages of block comments to explain the token bucket algorithm (or do…

Exactly, I dont want to have to go in and refactor a bloated class into 4 classes and then have to go refactor the short story they wrote about it.

But the new class(es) needs to be documented regardless as the relation to the code has changed from the old.

Keeping documentation in another document would see this going out of sync over time until the document doesn't at all reflect how the code looks. Not updating anything at all will leave others clueless of why the change was needed 4 months later and might see the other classes grow to the same size. Thus, eventually the code base will once again be opaque unless you ask the nearest person that worked on it last.

A nicer way of handling the flow of the document would be to use a literate programming tool that allows for keeping code snippets in an order which makes sense for the documentation rather than sprinkling as comments between the code. That way, code review happens at the same time as documentation review with code being local to the text documenting it in a format which is easy to understand for both.

Re: Writing Well-Documented Code – Learn from Examples

#142

Post by ainzzorl »

jpollock wrote: post #110
jpollock wrote: post #98

I had a lot of trouble reading that code. I kept getting distracted by the comments and missed the code. The code seems pretty self-explanatory. I have some changes I would make, but they really depend on performance vs depth (modulo the burst vs budget bug). // Hit the bucket bottom, let's auto-replenish and try again. self.auto_replenish(); Is ugly. Why repeat in English exactly what the code says? I don't even kno…

If we change the code, getting rid of if statements, it's easier to see what happens by removing if's. I've changed BucketReduction to be a pair, and fixed the strange behavior on error. Swapping "fromBurst" and "auto_replenish" would reduce the number of throttling events. This solution does have more branches than the original, hence readability vs performance. It's still not exception safe, auto_replenish could th…

This is a great comment: instead of making generic arguments, you actually tried to show how to do it better. Thank you.

I don't find the comments in the original code distracting, but I do like your version better.

> I'm also curious why burst is consumed, then budget. I would expect _budget_ to be consumed first (with refill) with overflow into burst? My expectation is for burst and budget to have different refill schedules in auto_replenish, so using burst first would result in more failures by missing refill opportunities.

This behavior is documented in the public API [0], so whatever is the reason why it was chosen, I don't think it can ever be changed.

> I don't understand why OverConsumption is different to Failure. Both will result in throttling by the caller. The reason for the difference should be documented.

My understanding is this. If the number of tokens requested is greater than the remaining budget but less than the size of the bucket, the call is rejected and the caller is blocked until it has enough tokens. But if the number of requested tokens is greater than the size of the bucket, the caller will never have enough tokens. Instead of blocking the caller forever, the rate limiter lets the call go through, but then blocks the caller for a while to compensate for the over-consumption. Here's the handling [1]. I wish it was documented better.

[0] https://github.com/firecracker-microvm/firecracker/blob/fc2e...

[1] https://github.com/firecracker-microvm/firecracker/blob/2f92...

Re: Writing Well-Documented Code – Learn from Examples

#144

Post by seanwilson »

SiVal wrote: post #120
pcmoney wrote: post #36

Personally I found most of those examples to be not great. I think they would be improved better names overall, more well named private methods and most importantly well structured companion test classes proving the behavior. I really dont want to read another developers comments on their mental state while I am feverishly debugging their code during a 3am page. The number of times I have been misled by an outdated c…

The problem with all discussions of good commenting style is that it's like debating good footware. Good for what? Office? Hiking in snow? Walking on the beach? Except that we have different footware for different uses but only one set of comments. Having such a limited commenting syntax is like assuming one permanent type of footware and debating which one would be best. I'd much rather have a smarter commenting sys…

> (this comment applies to this line, this one to the function, this to a group of functions...)

This is probably the major reason I much prefer introducing new variables and functions solely so I can give them descriptive names over using comments. Comments aren't scoped so they're often ambiguous and imprecise compared to code, which also contributes to them becoming out-of-sync with the code over time. Comments above a function definition are generally better than comments inside a function for example as it's clearer what the scope is.

Re: Writing Well-Documented Code – Learn from Examples

#145

Post by lloydatkinson »

rufus_foreman wrote: post #136

I went from my last job where every method and variable declaration had to be commented to my current job where there isn't a specific rule against comments in code but if you put in a PR with comments in it, you're going to get rejected after being laughed at. I thought I would miss it, but I don't miss the documentation. Code doesn't lie.

Sounds like a toxic environment.

Re: Writing Well-Documented Code – Learn from Examples

#146

Post by samsquire »

SquishyPanda23 wrote: post #111
samsquire wrote: post #90

Earlier quoted context omitted.

Long variable names mean you perceive your simple code as being too complicated. It's an if statement. I would refactor your long variable name to something more compact like enough_budget.

enough_budget for what though? That's not a very clear variable name.

total_traffic_budget

Re: Writing Well-Documented Code – Learn from Examples

#147

Post by samsquire »

SquishyPanda23 wrote: post #130
gnubison wrote: post #115

Earlier quoted context omitted.

IMO that should be in a comment, instead of duplicating that information every time you mention the variable. (This applies more for local variables in short blocks than for, say, global variables.) At some point the length of the name makes everything around it harder to read, since it’s been pushed so far apart.

As a general rule I completely agree. On the other hand, token bucket implementations are hard to understand and hard to debug. And an ambiguous variable name can cause trouble because some devs might think it "obviously" refers to enough budget for some other slice of requests. I think my preferred solution here is to extract the condition into a boolean function with a long name like HasBudgetForAllRequests. This s…

The words Has and For are unnecessary words in that variable name.

Think of code as mathematical notation. Some degree of familiarity with the domain is expected. You can use shorthand symbols or words as variable names.

Otherwise you're trying to write English sentences into compact notation and that's just noise. Hard to read.

Try read the A* algorithm when the variables have all been expanded out and you'll find it's impossible to see the forest for the trees. Sometimes G is the correct name for the collection of the cheapest scores known so far. It's compact and is best explained with a comment.

Re: Writing Well-Documented Code – Learn from Examples

#148

Post by RobertKerans »

kevin_thibedeau wrote: post #135
coliveira wrote: post #107

Earlier quoted context omitted.

That's why Knuth had the idea of creating literate programs where documentation and code was maintained in a single block. Unfortunately, this idea was never used in large scale.

Have you ever tried to read the soup he created with code blocks rearranged to suit the generated text rather than any future maintenance coder?

Yeah, I think there's a fundamental problem with the implementation -- with small, single-file programs where the code can be written in a chronologically linear manner it works well. But with that there's no need for reordering logic, so much of the more complex parts of weaving are redundant. Scripts, for example, are pretty easy to set up as [for example] markdown files, which works great (particularly in a project that requires a set of helper scripts which need why communicated -- having a set of markdown files in a folder makes it IME much more ergonomic for other devs). Anything larger and it gets increasingly fiddly and (again IME) not worth it.

Re: Writing Well-Documented Code – Learn from Examples

#149

Post by icholy »

rufus_foreman wrote: post #136

I went from my last job where every method and variable declaration had to be commented to my current job where there isn't a specific rule against comments in code but if you put in a PR with comments in it, you're going to get rejected after being laughed at. I thought I would miss it, but I don't miss the documentation. Code doesn't lie.

You're an idiot.

Re: Writing Well-Documented Code – Learn from Examples

#150

Post by alecbz »

rufus_foreman wrote: post #136

I went from my last job where every method and variable declaration had to be commented to my current job where there isn't a specific rule against comments in code but if you put in a PR with comments in it, you're going to get rejected after being laughed at. I thought I would miss it, but I don't miss the documentation. Code doesn't lie.

Comments like

x = 4 # Sets x to 4

Are of course silly and I'd laugh at them too, but comments when used correctly are hugely valuable.

Even a stale comment can be helpful in giving you a sense of what people were trying to do.

Do you not use commit messages either? Do you have any documentation at all?

Post reply on HN