Hacker News Reader

Comment by tschwimmer | Hacker News Reader

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.

View on HN

NetHack's source code is absolutely beautiful. It's probably the most well-kept, well-designed, well-structured and well-implemented K&R C program in history. Although they are switching to ANSI syntax soon. It's even more amazing because NetHack is (1) a video game, where generally speaking code quality is sacrificed for efficiency, and (2) it has been developed by a constantly changing team of volunteers over the course of over thirty years, and there still isn't any spaghetti.

Nethack suffers somewhat because the era in which it was birthed required a lot of portability, so there is a ton of #ifdef-ery which can be difficult to reason about.

#ifdefs are themselves spaghetti; windows.c [0a] and files.c [0b] have tons of platform-related ifdefs (but, mercifully, not too much nesting), hacklib.c [1] has some deep-ish ifdef nesting (though, again mercifully, well commented)

Ok on re-reading some of this, I guess it was worse in my mind than it actually is. Nethack was the first large codebase I ever made any changes to and tried to understand, so maybe the relative enormity at the time made a negative impression.

Check out the source for Brogue [2] for what I consider to be pretty readable game code.

[0a] https://github.com/NetHack/NetHack/blob/NetHack-3.6/src/wind... [0b] https://github.com/NetHack/NetHack/blob/NetHack-3.6/src/file... [1] https://github.com/NetHack/NetHack/blob/NetHack-3.6/src/hack... [2] https://sites.google.com/site/broguegame/

I bet they didn't have sprints and OKR like increasing the number of active users by 50% in one quarter. Nethack is a product of love to rogues and hobby software development.

I have to agree with that. I once decided to hack in the "Drunken Master" after the Jackie Chan film. If you are a martial arts master, then every booze potion you drink increases your attack and your defence (thought you still walk around mostly randomly). If you drink too many (I forget how many it was), then you fall asleep. I also added a fortune cookie that said, "A boat floats in water, but sinks in it too". I think it took me a couple of hours to go from never having seen the code base before to completing the hack. Really lovely stuff. Unfortunately, I don't have the code any more, but if anyone wanted to add it, it's easy ;-)

It seems like that's how this question is always answered. I'd also be interested to see some good application code.

Also curious about some good, not too hugely sized, game code (preferably something not written in C/C++, maybe like an indie game from the past decade or so). Anyone know something?

I almost feel like game code is a counter example. Unless you're making a massively multiplayer game, the code is throwaway because once you ship development effectively stops (or is limited for bugfixes and dlc). Would be interesting to see what the LoL or Warcraft codebase looks like though.

For C, how about ReactOS?

Redis would probably be better.

Any chance you could elaborate? How/why?

Redis is widely used in production environments. The code quality matters.

> Redis is widely used in production environments. The code quality matters.

That's how you judge source code quality? By measuring its popularity? And ignoring the actual code?

That's not what I said.

Keldon Jones’ Race for the Galaxy AI is brilliant. Every line is documented C. It trains and deploys a neural net. It has a fast and functional GUI. Most diehard RftG players have cut their teeth by losing to Keldon a few dozen times before really learning the game.

Keldon was contracted a few years later to develop the RftG apps on iOS and Android, which are easily worth $4.

Source: https://github.com/bnordli/rftg

Precompiled binaries: http://keldon.net/rftg/

> Every line is documented C

Every line? Oh dear [1]:

    /* Set verbose flag */
    verbose++;
    ...
    /* Set advanced flag */
    advanced = 1;
    ...
    /* Set expansion level */
    expansion = atoi(argv[++i]);
    ...
    /* Initialize game */
    init_game(&my_game);

I assume the verbose flag is incremented because there's multiple levels of verbosity, whereas the advanced flag is a boolean, and i is incremented because expansion is not a command line flag (rather, an option). But I wouldn't know that from the comments! Especially useful to know if like, verbosity actually has multiple levels, like -v and -v -v or -v -v -v and so on ... instead of knowing that init_game is ... init'ing the game.

Compare all those comments to this [2], which is actually a spectacularly useful comment.

Signal to noise ratio!

[1] https://github.com/bnordli/rftg/blob/master/src/learner.c

[2] https://github.com/bnordli/rftg/blob/master/src/replay.c#L94

Yikes, I've gotta agree:

    /* Exit */
    exit(1);

Well, yes, I see that. It might have been helpful to extend that to "Exit with an error status", perhaps, but as-is it tells you literally nothing that the code doesn't.

IMHO Coding guides should ban "SBO comments" Statin the Bleedin Obvious. Let devs decide what SBO is, usually its bleedin obvious.

Actually, this line:

/* Set expansion level */

    expansion = atoi(argv[++i]);

Is an example of ugly code. They're doing multiple things in one line, and in a confusing order.

# Increment i by 1.

# Grab the command line argument in position i

# Convert from string to integer.

# Assign to the variable expansion.

Note that there's no error checking to handle strings that don't convert to ints.

Arguably, any serious C developer can read this on the fly, but I seriously object to code with side-effects like the above ++i. It's often confusing to read and change.

I'm not criticizing the original author, more nit-picking on this as an example of great code.

I don't have a problem with that code. It is idiomatic C code, like *p++ or flag &= ~mask. ++i is a bit less common than i++ but nothing unusual. The lack of of error checking is more concerning though. It can be justified though, and it brings me to the next point.

The comment is the worst part. It is useless, it literally repeats the most obvious part of the code. A good comment would be something like "there is no error checking because arguments are already validated in the GUI, also 0 is an acceptable default".

For me, comments should not repeat what the code is doing. Comments are for expressing what is in the the mind of the developer that cannot be expressed in code. Example : "constant found using empirical testing", "Hermite spline formula" or "required on Windows". (Edit: the Hermite spline example is actually a bad one, a better idea would be to write a function called hermite_spline_formula instead)

If some coding rule require you to comment, find something to say about your code that isn't your code. It will also help you think more about what you just wrote.

> The lack of of error checking is more concerning though. It can be justified though...

How so, in this case? It could lead to undefined behavior.

> The comment is the worst part.

Useless comments may be irritating, but, as a bad practice, they are not comparable to skipping checks for possible errors and creating the possibility for undefined behavior.

It is not undefined behavior. atoi() returns 0 if no valid conversion could be found. Assuming argv[++i] is not out of bounds of course.

Useless comments are bad in part because they are sometimes not updated as the code changes, and no code analyzer will catch that. There is a reason some people say that comments are lies.

Most common example of what I've seen:

  // set foo to x
  foo = x;
  // set foo to x
  bar = x;

> Assuming argv[++i] is not out of bounds of course.

Well, you cannot assume that - look at the code (there are links to it) - there are several different ways in which it will go out of bounds.

What's more, even if it were the case that the worst that could happen is that the variable gets set to zero and the program terminates gracefully without doing anything, that would not amount to a justification for not checking for an error, it would merely be an observation that, fortuitously, this particular bug is relatively harmless, perhaps doing nothing worse than leaving the user unnecessarily puzzled over what went wrong.

Even the example you give here (which is not actually to be found in the code in question, and so could not possibly be a candidate for the worst thing about it) is relatively harmless compared to potentially causing undefined behavior, or (what is sometimes at least as bad) defined behavior that apparently works but which gives subtly wrong answers. And, by the way, code can lie too: identifiers can make claims about the semantics of a variable or function that are not always true. The only way to avoid that is to use meaningless identifiers.

The more you try to brush this off and argue that comments are worse than actual errors, the more obvious it becomes that your priorities are askew here.

Looking at the source, yeah, you are totally right. I was just looking at the lines out of context.

I was just thinking of cases where atoi(argv[++i]) was justified. Turns out I was overthinking it, it is just terrible code. No feedback on error, crash when the last argument is missing a parameter, static array with no bounds checking, a potentially leaky strdup. Comments are the least of the problems. It is a code smell though. A well justified one in that case.

I have to admit that until seeing this example, I thought that code commented this way did not actually exist, and that the possibility of it was just a straw man invented for the sake of argument!

It seems to follow the notion that more comments = better code. If the symbol names are explanatory enough, the code itself will be self-explanatory. Then all that must be commented about will be special cases handled/not handled and why a certain decision is taken about handling in a certain way.

Often, "every single line is commented" results from blindly following a certain "Standard" that demands that. Eventually generating meaningless comments all over the code. Then the important points never gets mentioned in the comments or just gets buried in the noise.

I actually find Chromium to be a lot more approachable than I assumed it would be. Have only really checked out the layout / graphics part of Blink, but it’s laid out pretty intuitively.

But yeah, Postgres also gets my vote. I guess there’s a bit of a bias there because devs are likely to read the code of the tools they use; either to track downs bug or just to understand how it works.

Yeah. I was amazed to find out it was designed so flexibly to inject C++ backed JS objects (eg write a request function which added requests to a queue after certain lengths based on multi-tenant fairness). Clients couldn’t circumvent because system code wasn’t necessarily in JS user space.

The latest version of NetNewsWire is a nice example of a modern MacOS application codebase.

https://github.com/brentsimmons/NetNewsWire

It’s just a demo app, but I find the ClojureScript re-frame implementation of the real world app to be the cleanest of the bunch: https://github.com/gothinkster/realworld/blob/master/README....

I think everything from Hashicorp is absolutely top-notch, working on their stuff taught me to be a much better Ruby and Go programmer.

I'm honestly surprised to see Hashicorp mentioned here, not because I've read their code, but because I had so many hours of tear-my-hair-out misery using their products.

I found them so under-tested and buggy that finally I just gave up. They're now blacklisted in my mind -- I'll never use one of their products again.

I guess the lesson here is that good code doesn't always have a strong relationship to a usable or bug-free product.

Have you by any chance also used their Vault[0]? I'm looking at solutions for secrets management and theirs is mentioned often.

[0] https://www.vaultproject.io/

I haven't and am not sure whom the target audience is exactly.

Azure and AWS have secrets management, and most stacks have some open-source way to do it if you're the roll-your-own-server type.

Yeah, cloud option isn't available for the product we're building (very specific needs with regards to data and services geo location).

But to me it looks like that the target audience is anyone operating a Kubernetes cluster as it seems to be the most mature option for managing secrets that is also well integrated into Kubernetes. And their open source version already provides quite a few features.

At least that's the vibe I got from reading various comparisons and blog posts about secrets management.

I think you should reconsider, I use their products daily (terraform) and have absolutely no issues?

To do what, though? All of their products are available elsewhere, but better integrated into our stack and IDE.

Discourse is a wonderful code base to peruse. When I was just starting out building more complex web apps I repeatedly referred to it to learn common patterns such as how queues are used to offload tasks.

Just to drive the point home, I was developing in Python and with no knowledge of Ruby, I was able to go through code using just github and I got what I wanted every single time.

It shouldn't be a surprise that developers are more likely to read and understand the source code of development tools

sqlite is the usual example of elegant code in a domain that often breads inelegant code.

Check out https://github.com/mymonero/mymonero-app-ios

Redis...

Reply on news.ycombinator.com