Ask HN: What are the “best” codebases that you've encountered? • Hacker News Board

Re: Ask HN: What are the “best” codebases that you've encountered?

#51

Post by Someone1234 » Mon, Jul 29, 2019, 6:56 PM UTC

h0bzii wrote: post #42

jakewins wrote: post #31

Earlier quoted context omitted.

Second this; Postgres codebase is what got me out of the "good code is self documenting" nonsense. For those of us in the database space it is an incredible resource - and overall a great example of good code. sqlite is much less complex, but similarly approachable. In more recent examples, I think you see a lot of this same reader-centric pragmatic ethos in many Go projects. The Kubernetes codebase comes to mind as…

/* don't even try to load if not enabled */ if (!jit_enabled) return false; I still think comments like these are super redundant and annoying.

It tells you the intent. The actual code does exactly that, because the intent matches the code, but sometimes the two aren't aligned and therefore the "redundant" comment can help you determine if the bug is the code or the intent.

Understanding the "Why?" of code is often the most valuable thing about comments. The code remains forever, but the "Why?" is often lost to time.

Re: Ask HN: What are the “best” codebases that you've encountered?

#52

Post by aerlinger » Mon, Jul 29, 2019, 6:57 PM UTC

omarhaneef wrote: post #30

I wish there was a way to read the codebase where there is a tag that tells you what the folder does. In github, rather than see what has changed, it would be interesting if there was a comment that told you what the folder contained. edit: Relevant here because the best codebase for me is one where I can understand the folder structure, but that is a sort of 0th order effect that should be equalized with some tool.

It sounds like you're describing a Readme file -- which by convention can exist as documentation for any folder and not just the project root. It's not adopted by all codebases but is becoming more common as source browsers like Github will render the readme as rich text when navigating to the folder.

Re: Ask HN: What are the “best” codebases that you've encountered?

#53

Post by jacquesc » Mon, Jul 29, 2019, 6:59 PM UTC

My personal favorite is Sequel. https://github.com/jeremyevans/sequel

Beautiful codebase, rock solid, and way better option than ActiveRecord IMHO

Re: Ask HN: What are the “best” codebases that you've encountered?

#54

Post by lloeki » Mon, Jul 29, 2019, 7:00 PM UTC

minitest. The testimonials speak volumes.

https://github.com/seattlerb/minitest

Apparently, some people think my toy channel implementation called Normandy is somehow good:

https://github.com/lloeki/normandy

Re: Ask HN: What are the “best” codebases that you've encountered?

#55

Post by tschwimmer » Mon, Jul 29, 2019, 7:02 PM UTC

Perhaps I'm jaded, but I notice that all the examples given here are developer tools or otherwise things with well scoped functional inputs and outputs (e.g. ffmpeg).

Anyone have an example of a consumer application that has a good codebase? Chromium, GitLab, OpenOffice, etc? I feel like such applications inherently have more spaghetti because the human problems they're aiming to solve are less concretly scoped. Even something as simple as "Take the data from this form and send it to the project manager" ends up being insanely complex and nitpicky. In what format should the data be sent? How do we know who the project manager is? Via what format should the data be sent? How should we notify the project manager? When should we send the report? Some of these decisions are inherently inelegant, so I feel like you get inelegant code.

Re: Ask HN: What are the “best” codebases that you've encountered?

#56

Post by omarhaneef » Mon, Jul 29, 2019, 7:04 PM UTC

PhilippGille wrote: post #46

omarhaneef wrote: post #30

I wish there was a way to read the codebase where there is a tag that tells you what the folder does. In github, rather than see what has changed, it would be interesting if there was a comment that told you what the folder contained. edit: Relevant here because the best codebase for me is one where I can understand the folder structure, but that is a sort of 0th order effect that should be equalized with some tool.

In Go, a folder is a package and as soon as you write a comment before the `package foo` declaration, it's package documentation. And thus GoDoc automatically generates a nice webpage out of it. See for example this package comment: https://github.com/golang/go/blob/master/src/net/http/doc.go... Turns into this documentation (the beginning only): https://godoc.org/net/http Out of the box.

Nice. I like the way it also shows you the functions inside a file/folder, and that clickable index is nice.

Re: Ask HN: What are the “best” codebases that you've encountered?

#57

Post by omarhaneef » Mon, Jul 29, 2019, 7:05 PM UTC

aerlinger wrote: post #52

omarhaneef wrote: post #30

I wish there was a way to read the codebase where there is a tag that tells you what the folder does. In github, rather than see what has changed, it would be interesting if there was a comment that told you what the folder contained. edit: Relevant here because the best codebase for me is one where I can understand the folder structure, but that is a sort of 0th order effect that should be equalized with some tool.

It sounds like you're describing a Readme file -- which by convention can exist as documentation for any folder and not just the project root. It's not adopted by all codebases but is becoming more common as source browsers like Github will render the readme as rich text when navigating to the folder.

readme files might be the natural place for them but in practice readme files sort of tell you about the project, the author, the purpose, examples of what it can do and maybe how to install it.

It rarely gives you what is in each folder, and what part of the functionality each folder handles, although perhaps we should try to change the conventions of readme files to include file structure.

edit: I mean the root readme might contain what is in each folder so you don't have to click on each one to see which one you want to start with.

Re: Ask HN: What are the “best” codebases that you've encountered?

#58

Post by dguo » Mon, Jul 29, 2019, 7:06 PM UTC

aerlinger wrote: post #52

omarhaneef wrote: post #30

I wish there was a way to read the codebase where there is a tag that tells you what the folder does. In github, rather than see what has changed, it would be interesting if there was a comment that told you what the folder contained. edit: Relevant here because the best codebase for me is one where I can understand the folder structure, but that is a sort of 0th order effect that should be equalized with some tool.

It sounds like you're describing a Readme file -- which by convention can exist as documentation for any folder and not just the project root. It's not adopted by all codebases but is becoming more common as source browsers like Github will render the readme as rich text when navigating to the folder.

Yep. For some of the larger projects that I've worked on, I've gotten into the habit of adding folder level READMEs. I don't know if anyone else has benefited from them, but I certainly have myself when I need to remind myself of some context or pitfalls.

Having a sensible folder structure and good folder names is nice, but taking a few minutes to write individual READMEs can make a repo even easier to understand.

Re: Ask HN: What are the “best” codebases that you've encountered?

#59

Post by SkyMarshal » Mon, Jul 29, 2019, 7:09 PM UTC

Peter Norvig's sudoku solver (Python) is excellent. Solves every possible variant of sudoku.

https://norvig.com/sudoku.html

Re: Ask HN: What are the “best” codebases that you've encountered?

#60

Post by kostarelo » Mon, Jul 29, 2019, 7:10 PM UTC

I've been enjoying reading Spectrum's codebase[0]. It's very simple, with little documentation you can understand pretty much what is going on and in the architecture level, is as simple as it needs. The first time I tried to open a PR, I was up and running my feature in a few minutes.

Small summary of the features I liked:

- Simple documentation

- Intuitive structure

- Lots of JS best practices, but still simple

- Event-driven architecture

- A simple API gateway that will just fire events to workers

- Properly divided workers (kind of microservices but with lots of shared code)

- Monorepo

It recently been bought by GitHub(1) and was discussed here(2).

The author has talked in his blog about some decisions he took wrong. Super interesting post(2).

0. https://github.com/withspectrum/spectrum

1.https://spectrum.chat/spectrum/general/spectrum-is-joining-g...