HackerTrans
TopNewTrendsCommentsPastAskShowJobs

ainzzorl

no profile record

Submissions

Writing Well-Documented Code – Learn from Examples

codecatalog.org
333 points·by ainzzorl·5 ปีที่แล้ว·142 comments

Code Catalog – a collection of code examples from prominent open-source projects

codecatalog.org
7 points·by ainzzorl·5 ปีที่แล้ว·1 comments

comments

ainzzorl
·3 ปีที่แล้ว·discuss
When did it become acceptable to write things about other people as he writes about Jeanine Banks? Even if everything he says about her is true, it still feels incredibly rude to say it in public.
ainzzorl
·4 ปีที่แล้ว·discuss
Software engineer from Moscow.

This is an absolute disaster for us. I can't imagine how and when we recover from this. The damage already made to our country is going to be devastating, and it's not even over yet. I even envy Ukrainians a little because they have a future (if they survive all this of course), and we don't.

Most people in my bubble, including myself, are strongly against the war. Many are fleeing the country. I'm currently on vacation abroad, and I haven't made up my mind if I'm coming back.

SWEs like myself probably are going to be the least affected by this because most of us can work for foreign companies just fine and make decent money, but most other people don't have this privilege and have nowhere to run. Generations of people are doomed to live in poverty because of decisions made by our genius of geopolitics. The old man actually thought we would win this war in 3 days and get away with it. I don't think he has a plan B. And I take his threats of using nuclear weapons very seriously.

While I blame Putin for most of this, I also think the collective West has gone mad too. The campaign to cancel, ban, boycott and belittle everything and everyone that has anything to do with Russia is out of control. People are not to blame for the actions their government. The talks like "let's hurt the regular people so they revolt against Putin" are just like that villain from Shrek: "Some of you may die, but it's a sacrifice I am willing to make".
ainzzorl
·4 ปีที่แล้ว·discuss
The best universities in the world make their courses available online for free - what a time to be alive! I wonder if it's still possible to make money selling online courses in CS.
ainzzorl
·5 ปีที่แล้ว·discuss
Not exactly this, but "Dragon's Egg" by Robert Forward takes place on a neutron star with a surface gravity billions times that on Earth.
ainzzorl
·5 ปีที่แล้ว·discuss
> Amazon basically didn't touch it since the acquisition almost a decade ago.

This is what I love about it. When something works for me (and Goodreads does), I don't want it to change.
ainzzorl
·5 ปีที่แล้ว·discuss
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...
ainzzorl
·5 ปีที่แล้ว·discuss
While I agree with the general sentiment, the first example in the article IMO demonstrates how "what" comments make understanding code easier. When I first read that code, I was pleasantly surprised how easy it was to understand everything going on there, even though I had no familiarity with the code base. This is rare for non-trivial projects. I'm not sure if it could be made as clear without those comments.
ainzzorl
·5 ปีที่แล้ว·discuss
A lot of code files starts with lengthy copyright notices, and no one seems to mind. I find comments at the top very easy to ignore if I work on that code regularly. Also, I don't think I've ever seen comments at the bottom of a file!

I wonder if Protobuf wasn't open-sourced by Google, that comment would've been replaced with a link to a design doc. Google docs weren't a thing in early 2000s when Protobuf was originally written though.
ainzzorl
·5 ปีที่แล้ว·discuss
Thanks! If you know some good examples, please consider proposing them: https://github.com/ainzzorl/goodcode/issues/new?assignees=&l...
ainzzorl
·5 ปีที่แล้ว·discuss
I agree that some comments in the first example are unnecessary, e.g. the one pointed out in [0], but I find comments like that at worst useless, but not harmful. They have a potential to become harmful if someone updates the code but doesn't bother to update the comment, but I can't see how it takes away the ability to scan the code.

[0]: https://news.ycombinator.com/item?id=28416777
ainzzorl
·5 ปีที่แล้ว·discuss
Lambda indeed is not the right tool for this. It sounds like you need some infra that can auto scale - there are many ways to do it on AWS (EC2 auto scaling, ECS, EKS), any other cloud provider, with Kubernetes...
ainzzorl
·5 ปีที่แล้ว·discuss
Please consider adding an FAQ about how it compares to "native" AWS offerings, because it resembles a few of them.

E.g. Lambda ("run your code" without "start a cloud server" and "turn it off"), ECS (runs containers, can run a standalone task too), Fargate, Batch... The "running JupyterLab in the cloud, with automatic timeout" use case is supported by AWS Sagemaker.

Disclaimer: I'm a former AWS employee.
ainzzorl
·5 ปีที่แล้ว·discuss
Sounds cool!

Will it support only "basic" DynamoDB features (reading/writing records) or some "advanced" things too, like GSIs/LSIs, streams, fine-grained access control, TTLs, backups?
ainzzorl
·5 ปีที่แล้ว·discuss
I've been assembling and annotating a collection of instructive and self-contained code examples from open-source projects, to make it easier to learn by reading good code.

Code Catalog: https://codecatalog.org
ainzzorl
·5 ปีที่แล้ว·discuss
Yes. I was thinking to start with smaller examples showing how they write code at <big project> without necessarily understanding the big picture, but bigger examples would be great too eventually. Something like http://aosabook.org/en/index.html already mentioned here.
ainzzorl
·5 ปีที่แล้ว·discuss
You blog about interesting things, subscribed :-D
ainzzorl
·5 ปีที่แล้ว·discuss
Replied in another branch: https://news.ycombinator.com/item?id=27687724
ainzzorl
·5 ปีที่แล้ว·discuss
I started a repository for it: https://github.com/ainzzorl/goodcode. Please follow!

It's empty for now, but I included a few examples [1] of what I'm going to annotate and add there.

[1] https://github.com/ainzzorl/goodcode#examples
ainzzorl
·5 ปีที่แล้ว·discuss
> "There are so many projects on GitHub – pick one you like and see how they did it." But most successful projects are quite large; where do you start from?

I'm working on a slightly similar project motivated by this problem: how do you learn from established open-source projects - most interesting ones are too big, too complex, to hard to get started with.

So I'm compiling a collection of interesting code examples from open-source projects and explaining/annotating them. I'm trying to pick examples that are:

- Taken from popular, established open-source projects.

- Somewhat self-contained. They can be understood with little knowledge of the surrounding context.

- Small-ish. The can be understood in one sitting.

- Non-trivial.

- Instructive. They solve somewhat general problems, similar to what some other coders on some other projects could be facing.

- Good code, at least in my opinion.

I'm planning to share it in a few weeks.