Ask HN: What are some examples of good code? | Hacker News Reader

Ask HN: What are some examples of good code?

321 pointsamingilani162 comments

I keep reading on HN that I'm order to become a better developer I need to write code everyday, and more importantly read other people's code.

What are some examples of good code that you've seen?

Personally I'm interested in Ruby on Rails and I've recently started going through GitLab-CE[1] but what is your favor code?

[1]: https://gitlab.com/gitlab-org/gitlab-ce

View on HN

Writing code is really a modelling problem: you write down code that describes the model that's inside your head. When you're done, you're left with both working code on a hard drive, and a new, better model inside your head, because you understand the problem better.

So, reading someone else's code can be like reading a model of something that has gone through dozens of iterations, where the bottleneck isn't really understanding "the code", but understanding the thing that is modelled, which the people writing the code are intimately familiar with, unlike you[1].

In my opinion, developing this modelling skill, in yourself, is much more important than watching the result of someone else exercising their modelling skill. A lot can be learned from observing someone else's solution, but this will always be secondary to learning how to craft your own.

[1] For example: try reading compiler code. People have been writing compilers for so long that reading and understanding this code isn't about understanding the actual code, but about understanding how a compiler is modelled (scanning, lexing, parsing).

I completely agree. I've been thinking of replicating a mid-sized project written by a programmer that I respect so that I think a lot more about the model before comparing the code.

Not Ruby but for C code, I like Redis's code:

https://github.com/antirez/redis/tree/unstable/src

I don't personally use the product, but I find the source well written and always share it as an example of nicely done C code.

Here is some nice Erlang code I like -- network packet parsing:

https://github.com/msantos/pkt/tree/master/src

Notice how concise this is:

    codec(
       <<4:4, HL:4, ToS:8, Len:16,
       Id:16, 0:1, DF:1, MF:1, %% RFC791 states it's a MUST
       Off:13, TTL:8, P:8, Sum:16,
       SA1:8, SA2:8, SA3:8, SA4:8,
       DA1:8, DA2:8, DA3:8, DA4:8,
       Rest/binary>>
    ) when HL >= 5 -> ...

This is due to the beauty of binary pattern matching. You could kind of do it in C by casting to a struct but notice here it is also calculating header length (HL) as part of the match operation. So it can do a bit more than just casting a binary blob to a struct.

Another thing here is that it is also big endian by default so there is not need for htons(), htonl() and such functions sprinkled throughout the code.

Not disputing the code quality of either above project, but over valuing brevity / being concise is a common cause of problems. Specifically, people will often sacrifice readability and robustness for brevity.

At this point in my career I don't really value being concise at all. Which is not to say you shouldn't ever think about "Can I write less code here?" but the goal there should be writing less code to make what you're writing more robust, more stable, more readable and not just shorter.

If there's one thing I could tell every programmer early in their career (including a younger me) it would be; nobody's going to be impressed with how clever you were when they're frustrated trying to understand what the heck is going on. Including you in 6 months.

It's amazing that this is still highly debatable in our industry. Always write to make debugging easier. Always. There's so many people that worship cleverness over readability.

In all fairness, a stunningly clever insight can make things seem so obvious that you forget how hard it was to have that original insight.

This kind of brevity is extremely helpful when thinking about a problem. You "just" have to grok the mechanics thoroughly. This really helps in designing effective higher level abstractions.

Unequivocally admonishing brevity for ostensible readability kind of ignores the trade offs. I think there are other ways to bootstrap grokkability without having to sacrifice the conceptual clarity of nicely compact code.

As someone taking a lot of ML/AI courses ( a subject new to me) , these clever insights are popping up all around me lately, and I agree once you learn it, it's hard to imagine what it was like before.

I'm hitting a lot of 'aha' moments which has really been emotionally satisfying, it's been a long time since I had to push myself I guess.

There is a difference though when it is something custom and new (say if this code defined or parsed a new protocol) vs parsing an existing protocol. Notice https://tools.ietf.org/html/rfc791#section-3.1 section diagram. That code is basically an almost perfect translation of the RFC diagram, down to the bits involved. That is the beauty here: minimal impedance mismatch between the specification and code.

You can eliminate the impedance mismatch entirely by using the specification as your code [1], as Alan Kay's Viewpoints research team did. ;)

[1]: http://www.moserware.com/2008/04/towards-moores-law-software...

Ha! Interesting, just feed the diagram to the code.

As a side, what are some good ways to start understanding the bigger projects? Blogs and documentation are helpful but mostly don't talk about the underlying implementation details.

Digging through the code line by line takes a long time and while one does learn a lot, I am sure there has to be a better way of doing this.

Any static analysis tools that help in this regard? Or any other tool/approach that you might recommend?

I am leaving my current team, in part for this very reason. Senior technical people in the organisation don't value readable, understandable code, favouring 150 character one-liners instead. It's proven to be a very effective way of increasing the time taken for anybody except the author to debug issues. In my view, this has increased the perceived value of those responsible.

I'm sure that wasn't their ultimate intention but there's certainly no incentive to change!

The Redis code doesn't look exceptionally good to me. I just looked through five files, but things like spacing and the use of braces seem to be pretty inconsistent. There are also a lot of magic numbers and quite a few variables have poor names.

Noticed those too, also I don't personally like camelCase in C however I still like the code because of how it is laid out and solves the problem. It has the right amount of comments (too many of those is also bad), some functions are large but overall has the a good balance there too.

Also for an example it is also the right sized project. It i not too small and not huge (like Linux kernel) and the overall structure can be understood in a few hours of browsing through.

I agree that things like spacing and inconsistent use of braces may cause code not to look good, but don't really feel it is a surefire indicator of the code not actually being good.

#include "lzfP.h"

# define FRST(p) (((p[0]) << 8) | p[1])

ref = hslot + LZF_HSLOT_BIAS; hslot = ip - LZF_HSLOT_BIAS;

I pity all C programmers who have to deem this beautiful

That looks clear and concise to me.

It's a part of a performance sensitive mission critical infrastructure. The parts you posted are some of the core data structures that make it fast by squeezing every bit and byte that reasonably can. There are no points awarded for being pretty.

A quick browse around Redis source code looks very clean and elegant to me. There are "hard" low level parts like the stuff you quoted (out of context) and then there are "easy" parts that implement the higher level functionality. It has a decent amount of comments.

Taking one of the "nasty" bits out of context is disingenuous. Every computer program has nasty bits and they're usually there for a reason.

> That looks clear and concise to me?

What's a FRST? The actual code appears to do a LE encoding of a u16, but I can't fathom why you'd call that "FRST". But maybe in context it makes more sense.

The rest, IDK. Can't tell what an "LZF hslot bias" is. Again, might make sense in context.

None of this code was meant to be understood without background knowledge of the algorithm internals - and some code just is that way. You don't go reading rbtree.c without first reading about Red-Black Trees in your algorithms book.

If I recall correctly, the file you grabbed these from had a lot of comments that thoroughly explain how it works. At least many other files in the redis repo do.

They could have named it "FIRST" or whatever FRST is short for. That would have made zero impact to the code quality but a longer name would make things clumsy. It's a file-local helper macro and not a part of any public interface or a crucial piece of the architecture.

Feel free to disagree, but picking two nasty lines out of context in an otherwise well designed and implemented code base has zero bits of information about the quality of the project.

A URL to the actual source helps, I think, to put it in context: https://github.com/antirez/redis/blob/d680eb6dbdf2d2030cb96e...

The parent poster didn't link, so I lacked the context to really evaluate it. Your persistence at waving this away as "making sense with background knowledge of the algorithm internals" drove me to find it.

> If I recall correctly, the file you grabbed these from had a lot of comments that thoroughly explain how it works

It's fairly light on comments. Not completely devoid of them, but the code can't stand in isolation. The algorithm itself, LZF, seems to be a variation of LZO, but not notable enough to make Wikipedia.

> They could have named it "FIRST" or whatever FRST is short for.

The fact that you're unsure of this fact defeats your next point, at least for me:

> That would have made zero impact to the code quality

Why? One extra letter immediately disambiguates it, and now we know that it at least means "first".

> a longer name would make things clumsy

If you look at the file it's used in, it has exactly two uses. The readability gained from the extra vowel in this case is well worth it, and would in no way make the code "clumsy". A four-byte (five if you count the commented out code) change so that the reader doesn't need to play guess-the-word? Worth it, in my opinion.

The documentation above it too,

> just believe me, it works ;)

But why does it work? We'll never know, b/c that's bound up in the author's head.

This is perfectly fine and readable. No need to pity anyone, especially not C programmers. :)

What you show in Erlang example is just a syntax. The surrounding code or usage or approach may be bad/ugly. It has nothing to do with code quality.

This stuff about "reading code" is basically bullshit and nobody does it. http://www.gigamonkeys.com/code-reading/

> Seibel: I’m still curious about this split between what people say and what they actually do. Everyone says, “People should read code” but few people seem to actually do it. I’d be surprised if I interviewed a novelist and asked them what the last novel they had read was, and they said, “Oh, I haven’t really read a novel since I was in grad school.” Writers actually read other writers but it doesn’t seem that programmers really do, even though we say we should.

> Abelson: Yeah. You’re right. But remember, a lot of times you crud up a program to make it finally work and do all of the things that you need it to do, so there’s a lot of extraneous stuff around there that isn’t the core idea.

> Seibel: So basically you’re saying that in the end, most code isn’t worth reading?

> Abelson: Or it’s built from an initial plan or some kind of pseudocode. A lot of the code in books, they have some very cleaned-up version that doesn’t do all the stuff it needs to make it work.

I don't read code just to learn in general, but I read it to find specific undocumented details or to figure out how someone solved a particular problem. Of course, you've got to read a ton of code if you're working in a large project.

It is a great way to find new ways of doing things, and to gain experience-based opinions, but I certainly wouldn't be doing it if I didn't have a very specific goal in mind.

Most novelists are bad. Most devs are bad. No one seems to know how to tell they are a bad one, but I think we have a good filter: do you voraciously read other people's work?

Code in books is dumb. The real code to read is other code you use or interact with. eg reading the jquery source or the Rails source or code reviewing a colleague.

Almost always one does this while answering a question about this source. Trying to understand what a library call is doing or tracing a bug.

You learn a lot this way including coding tricks and style points.

> This stuff about "reading code" is basically bullshit and nobody does it.

Some guy says in an interview it's bullshit, so it is?

You never read other people's code? Not when the documentation's lacking? Not when the documentation's fine, for a framework say, but you need to see an example of how it's actually used in the context of a real application?

The implication that I get from the quote is that people don't read code for the sake of reading code.

And that matches my experience: When I read code, it's precisely because the documentation is lacking, or because I want to match up an error message produced by the code with the logic preceding the error message's origin.

Or, quite often, you read it because you want to change it - to extend it or to fix a bug.

I think the best way to both read code and gain experience is to set a goal of at least weekly or monthly contributions to a couple of open codebases that benefit your life.

But if you look at the article you'll see what I think is a salient point -- looking at code and figuring out how it works often looks more like an "investigation" (like, set some breakpoints and step through it, for instance). It's nothing like sitting in front of a fireplace with a novel.

Choose your own adventure books are still reading though.

I think that there's also a much more similarity with analyzing a novel than reading one for pleasure. Reading code has a much greater mental tax than pleasure reading, it requires more focus to actually put together what's going on, and that's similar to analyzing a novel for a report, where you might read the same passage 4-5 times, taking notes. Or even better yet, analyzing a poem, which are often short (and often obey 80 char line width rules!) and analyzing them can require a great amount of focus and thought to decide why a poet used this word in this way, and what meaning they intended to convey and such. That's much more similar to reading code than reading a novel, and I expect also less common.

I wouldn't call Abelson just "some guy" but you obviously didn't click through and read what the article says.

Indeed...hardly human.

I mean that's all definitely true but if you consider that you're trying to pick up new motifs, different ideas, and understand how people organize the thought and concept behind their code, reading another person's code is invaluable. I think the tricky part comes with looking for quality code. One should go in with an open eye looking to satisfy what you're trying to solve, and read enough to learn how to do that oneself. I don't think casual reading of code will ever be as entertaining as a novel, but if you want to get better by solving specific problems it is a great way to go.

I'm managing a side project with four devs and I read lots of code. Since It's all performance-oriented algorithmic code, reading is the only way to know what's going on. And none of the code is crudded up. It's actually pretty nice.

Looking at the code of a project you're working on or managing isn't really the same as just sitting down and reading code for the sake of it.

The thing is, reading code is hard. Even well written code is hard to read and grok, the other kind can take days to absorb.

But it is very effective as a way of spotting certain kinds of bugs, while at the same time gaining a much deeper understanding of a codebase.

Reading code in a non trivial way is a very special skill that not many developers have, but that is very worthwhile to attain.

Whenever I come to a new codebase, I start by grabbing a pretty random bug and reading the code in that area. just flicking through, forcing myself to ask questions about it and finding out the answers.

actively engaging with code like that is an amazingly effective way of absorbing a codebase.

Personally I find it easier to read code than to read an English explanation of the code. Obviously comments do help with reading code but in general it's the code that really explains things for me rather than the human description.

I suspect this might be a side effect of my dyslexia, but it's something which often works to my advantage.

I disagree. Especially when switching from one framework or language to another, it's a great shortcut for picking up on idioms.

Maybe not too many people read code just to read code, but you absolutely have to read code when working on a project that's not your own, and that experience is very valuable.

I read others code in code reviews, and as necessity to get the job done. I very occasionally read others code say in GitHub, but not for any desire to get better, but out of curiosity. But when I do that I get bored quickly!

The single most important change I've made in how I learn new tools/frameworks/whatnot is Github code searches -- I spend far more time there than on StackOverflow. Maybe this is more important in Scala land, where there are far fewer books and talks and blog posts to work from, and the tool stack is evolving a lot more, but I've found answering many questions of structure / "How do people incorporate this concept into a larger application" to live largely in code.

The answer is never exact, though. Something will have 10 different solutions, and being able to look at them and discuss the tradeoffs that went into the decision is a definite skill.

I wonder what Fabien Sanglard would think of this.

To me, the Quake 1/2 source code has been an invaluable source of insight, as much for small algorithmic stuff (like collision/sliding code) than for its architecture as a whole (like game/engine separation, the edict_t system) ...

Have you never asked yourself "how did they do this" ?

You'll end up reading code if you work on code. Find something to work on. (I don't know what you should work on.)

Just like you can't really learn math just by reading the book, you'll "learn good code" much more effectively if you're working on it and you have to make decisions and judgments to move forward.

> You'll end up reading code if you work on code.

This.

Also, you'll have a more goal-directed path through the code, which is usually more motivating than understanding code for the sake of understanding.

Of course, there's always the pitfall that people will start making changes willy-nilly, until the code does roughly what they want, without really understanding anything.

But this will vanish as soon as you put higher quality standards to your own work. (e.g. if you want to ensure that it does the correct thing in all edge cases, or if you produce something larger than a quick hack)

> e.g. if you want to ensure that it does the correct thing in all edge cases, or if you produce something larger than a quick hack)

... if you submit your code to the project's owner. :)

But you'll notice this is nothing like the idea of "reading code" for the sake of it.

You've never thought "gee this is really cool software, I wonder how they implemented xyz..."?

While he might make a few usable points, this article is drenched in non-recognized bias. He takes his (as I see it, heavily bottom-up leaning -> 'in order to grok it I have to essentially rewrite it.') cognitive style and applies it as universal.

Except that what led him to this point was interviewing multiple world-renowned programmers for his book "Coders at Work" and finding essentially none of them read code regularly either.

Still making it only anecdotal - and even more obviously biased (I'd hazard a guess that the interviewees are quite far from the norm in how they learn...)

OK, sure, the data set is small. Do you know anybody who actually does it? Have you seen them doing it?

Yep. I do it, for example. A few of my colleagues do it. Others work more like described in the article.

(But I know that I myself are somewhat of an outlier, since I'm a rather extreme top-down learner.)

Spot on. Most of the time I can barely stand reading my own code, so how about I take a break and read some barely intelligible code written by someone else, using a different coding style and a different mindset? Wreck my brain trying to figure out what on Earth the other person was thinking when they wrote that abomination. You know, just for the kicks.

Wrecking your brain trying to figure out what another person was thinking is a pretty fascinating way to appreciate the incredible complexity of human beings and how other minds work differently than your own.

When you do it as a day job for prolonged periods of time (where the other people put little to no effort into writing code that doesn't resemble raw encryption), the fascination wears out real fast.

You'll find some great examples in a variety of languages on The Architecture of Open Source Applications site:

http://aosabook.org/en/index.html

This book is amazing

SQLite/Fossil source tree is a piece of art, practically every single function is well commented, written in clean C, easy to read. DRH has done an astonishing work. I'm impressed by his work. In my company where we do embedded C, the programming style is based on him. https://github.com/symisc/

I took a quick look recently at id software's GitHub repos of their old blockbuster games (Wolfenstein, Doom, Quake) and gotta say it was the first-ever C codebase I encountered that I found eminently readable.. (whether it's "good C", I can't assess though)

I agree, the id code is very well organized and readable.

Doom original C sources what made me realise how simple and powerful C could be.

https://github.com/id-Software/wolf3d

https://github.com/id-Software/Quake

https://github.com/id-Software/Quake-2

https://github.com/id-Software/DOOM

Just reading the first couple replies to this thread, there seems to be some confusion regarding what code quality IS. Two broad categories:

1. Micro code quality. Looking at a single file, someone makes statements about code style - spacing, variable naming, etc. - things you would find in a style guide like PEP8.

2. Code Design. Testable code, the absence of edge cases where unnecessary (for example, turning the root of a tree into an edge case) and broader design questions; and things like correct choice of algorithm.

Code quality kind of encompasses both, but its obvious how you can be bad in one category and still be really good in the other. Really good code is good in both, but if I had to pick, I'd like to be good in category 2 first at the expense of 1. Assuming 2., 1. can be improved easily.

I'd like to say something about concise code as well. Concise code, or code that does a lot in very little lines can be treacherous. This can be fun when your team is all very senior C programmers who actually understand all this code. Then, brevity is good, but when you work in open source, or write software that has to be read by people who are inferior to you, being concise may not be the way to go.

This is almost similar to premature optimization, but not really. People who write really good C code optimize - but not prematurely. They just know that what they're doing is efficient.

https://github.com/pallets/flask and https://github.com/kennethreitz/requests

both in python, but beautiful code, well structured and you would not need any docs, just read the code

Flask is absolutely beautiful; definitely agree with reading through it.

I don't want to take anything away from requests. It's an extremely useful library. However, I do a code walkthrough of various popular libraries with my students and I've never been satisfied with requests internals. The emphasis, I've felt, is more on clean, stable, public API rather than internal consistency and cleanliness. I don't pick it up these days for my classes. Instead, we usually go through the python standard library. Especially the code from Raymond Hettinger.

that sounds like a class I would love to take. any suggestions on what in the standard library to check out?

We usually do collections. Especially the implementation of the OrderedDict. It's a nice combination of compromises, careful coding and usefulness.

I used to do requests but like I said, moved away. I sometimes do pygments to discuss how different lexers etc. are "plugged" in and also to show how messy the command line parsing code there is.

This batch will probably be a little different since I'm reworking it completely. The syllabus for the first batch is here if you're interested in what we covered http://thelycaeum.in/blog/2014/06/10/mentoring_course_time_t...

This was also asked a year ago, and I pointed to Zach Tellman, and that comment was upvoted by others. I'll post the same again. Because he always has excellent reasons for the decisions that he makes, I find it interesting to read his code and try to figure out why he made the decisions that he did. This is in Clojure:

https://github.com/ztellman/manifold/blob/master/src/manifol...

Also, it is fascinating to consider how Go routines were implemented as part of Clojure core. Huey Petersen wrote a fantastic analysis of how state machines were used to implement Communicating Sequential Processes:

http://hueypetersen.com/posts/2013/08/02/the-state-machines-...

You can read along while looking at the source code here:

https://github.com/clojure/core.async

This is a great implementation of Communicating Sequential Processes, first described by Tony Hoare in 1977:

https://en.wikipedia.org/wiki/Communicating_sequential_proce...

This is the same technique that Javascript/NodeJS uses to implement its async.

I've read that Redis (https://github.com/antirez/redis) has well written code, in C.

It is very good.

I've also heard that Redis is incredibly well written. However, is it common for production C code to have a single file with 5,300+ lines?

https://github.com/antirez/redis/blob/4.0/src/cluster.c

https://github.com/cyrusimap/cyrus-imapd/blob/master/imap/im...

cough

Yep

> However, is it common for production C code to have a single file with 5,300+ lines?

It's definitely not uncommon, but yes, that file is on the long side. However, it is rather clean and well-organized.

It may be due to the poor module system (header files) of C where you end up making files slightly longer than ideal because splitting into two files means also adding some header files and thus adding to the maintenance burden.

When writing C code, I usually strive to put a whole "module" in a single file, so that no "private" interfaces have to be put in header files. Everything that needs to be exposed in order to test a module goes in the public interface.

It's a tradeoff and C being C doesn't help (and C++ wouldn't really help here IMO), but I see nothing wrong with the file you picked. It's a bit long but it looks well done to my C programmer eyes.

Right off the bat, I see multiple instances of str* functions where strn* functions should be used. I'm also wondering about this variable "server" which seems to have an unknown definition. There are lots of gotos, and many other deferred high-quality conventions, such as explicit parenthesis in comparisons, re-ordered fields in comparisons, chains of else ifs, where a switch would be preferable.

I also see lots of prototypes (all?!) defined at the top of the file instead of in a header file. They could be made static.

Also, the generic type "int" isn't a good idea because it can change, it helps avoid porting problems to specify the size (int32_t, uint64_t, etc.)

And the memcpy()'s should be changed to memcpy_s().

On the bright side, the comments are quite good and plentiful. Refreshing!

I like most the python code written by Norvig in http://norvig.com/python-lisp.html and other parts of his site. It's very expressive and simple. Real code will have much more corner cases and logging and error handling crust but still should tend to this simplicity

A few weeks ago, I spent some time in reading O'Reilly's Beautiful Code (http://shop.oreilly.com/product/9780596510046.do). The book is essentially a collection of essays from various programmers describing what they think of as beautiful code.

I particularly liked Brian Kernighan's description and implementation of a regex matcher, and Travis Oliphant's discourse about multidimensional iterators in NumPy.

Worth a read.

One of the first tech talks I remember was Bryan Cantrill at Google, and I vaguely remembered that he mentioned at the beginning of that talk that he had contributed to a book called Beautiful Code, so I double-checked and it seems to be the same book.

Looking back up the talk, it points to his review of the book here: http://dtrace.org/blogs/bmc/2007/07/28/on-the-beauty-in-beau...

> More specifically: read [two specific chapters with very different attitudes on what makes code beautiful]. It seems unlikely to me that one person will come away saying that both are beautiful to them. (And I’m not talking new-agey “beautiful to someone” kind of beautiful — I’m talking the ”I want to write code like that” kind of beautiful.) This is not meant to be a value judgement on either of these chapters — just the observation that their definitions of beauty are (in my opinion, anyway) so wildly divergent as to be nearly mutually exclusive. And that’s why the title is perfect: both of these chapters are beautiful to their authors, and we can come away saying ”Hey, if it’s beautiful to you, then great.”

I don't even like Python (Ruby guy myself) but the various stuff Peter Norvig has done (typically in Python) for demonstrating coding problem solutions. I think you benefit the most if you try doing the problem yourself (like the Advent of Code series), and then compare your solution to his.

What I've often found is that Peter is just great at isolating the minimum required model/data structure. More often than not, when I notice his solution has half the code of mine, it's because I used the wrong model.

I really like Unicorn[1]. It's a very well-architected webserver with a nicely structured codebase. Reading the code has taught me about some neat tricks, e.g. self-pipe trick, and a lot about `fork`.

Additionally, I've on occasion consulted the Linux kernel and PostgreSQL repos. Would recommend, although I'm definitely either lying or very ignorant if I said I was familiar with them.

1: https://github.com/defunkt/unicorn

PostgeSQL has some very easy to read and well documented source code. Great place to look if you need anything related to db data structures.

The implementation of Project Oberon. It is so sensible that it can be hard to notice the magic.

http://www.projectoberon.com

That is a good read for many reason. Recommended to anyone interested in programming, operating systems and software architecture.

You can learn what constitutes good code by reading bad code- it is safe to assume that there is a lot more bad around than good! Some flags:

-God objects (they do everything!) and their opposites, freeloaders

-1000-line methods

-No unit tests

-Not-invented-here syndrome, otherwise known as "let's write our own array class!"

-No separation of concerns (everything mashed together)

-Not concerned with issues such as performance, maintenability and security

After you look at too much bad code (which, by the way, will include your own), you acquire a very instinctual understanding of good practices.

I think another way to put many of the items on your list is that the code should read as a description of what it intends to do, rather than how it intends to do it. Breaking code into components and giving those components useful names goes a long way towards achieving this goal.

For me, at least, this helps with the act of writing the code, in addition to the act of reading it. I am not nearly smart enough to keep in mind all of the things that need to be done to write solid code. So I compensate by developing abstractions that let me forget about details, assume they're handled (for the moment) and focus on just a small part of the problem at hand. The act of writing the code in that way tends to lead to a more manageable style.

> -Not concerned with issues such as performance, maintenability and security

This is where engineering sense comes into play. I'd personally rather not pay for things I don't need, particularly if an undue focus on performance, etc. means my cost overruns my budget. Perfect is the enemy of the good, and all that...

"This is where engineering sense comes into play. I'd personally rather not pay for things I don't need, particularly if an undue focus on performance, etc. means my cost overruns my budget. Perfect is the enemy of the good, and all that..."

I agree, however, making at least an effort is preferable than not caring.

What I had in mind was the developer of a legacy system at my previous work. He couldn't understand why I was fussing over performance metrics and I told him I couldn't understand how he could not. The reply was that they had enough trouble "making the bloody thing working", so anything else was peripheral.

For me, the question would be why you cared about the performance metrics. Sometimes bad performance can be a sign that something is fundamentally broken, and fixing the metrics might be the solution to the stability problem. Sometimes, it's less important and more of a distraction. Usually, it's not to difficult to put together a case that performance issues are impacting stability.

"-Not-invented-here syndrome"

The counter to this is dependency hell. I oft times see developers pulling in large, new and compiled dependencies into Python projects for a single pieced of functionality just to avoid being accused of "not-invented-here".

Bad code is boring, because you quickly lose context or get confused by the 'bulldozer' approach that such code usually assumes.

So it won't help if you try and read it.

To paraphrase Tolstoy's quote about happy families: "All good code is alike, yet each bad code is bad in its own way".

I remember a piece of advice from some guru programmer I've read some time ago: "Don't just read the code - compile the program and try and change something in the code, maybe the window title, maybe add a menu item - something silly, but which forces you to figure out where things are done in code."

I love reading Oleg Kiselyov articles/papers. Just a few lines of Haskell or ML and some amazing concept is unlocked. A great exercise is to port some of his code to a language of your choice.

http://okmij.org/ftp/

One of my favorite simple examples of what clean and elegant code can be is Peter Norvig's spellchecker: http://norvig.com/spell-correct.html

It's in Python and a single file but it comes with a wonderful description and shows how a complicated task can be broken down into a few small and powerful functions.

But small systems are easier to get nice. Once they are not small it is there where all the hell begins. Alas, it is a big systems where nice code helps most.

Definitely true! You also have the luxury of tweaking every line of code for a small system to get it perfect.

It's also the reason for trying to break down larger systems into smaller, elegant components.

I don't have an example to give, but i can offer this.

During the prototype phase, anything goes, speed is paramount, you just have to make it sort of work. Don't get hung up practicing pretty looking code during this phase.

You should always practice, but don't get hung up.

Prototype given the green light? Ready to dive into the build phase?

I'll say this, google for "coding style guide"

The challenge with style guides as an approach to "nice code" is they often focus on the code equivalent of writing a grammatically correct line of code -- things that can be often caught with a linter.

Where I see things fail a lot more is in the code equivalent of "How do I structure a paragraph" or "How do I organize this paper", which most things under the "style guide" umbrella don't cover.

I've always thought of the "how to write grammatically correct code" style guides as being relevant to writing high quality code in the context of a team that may onboard a new person or an internal transfer: they provide some baseline guarantee (insofar as the team honors them, of course) of the structure and formatting of the code. This reduces some amount of friction in a team. The benefits provided are largely context dependent (e.g. they'll benefit teams that expect to have a couple of senior engineers and many juniors on a relatively constant basis more than a team of experienced engineers in general), but I think having a style guide is important for any "large enough" engineering organization.

I've also always insisted on including at least some loose guides to cover the "how do I structure a paragraph" cases. These generally are going to vary on a project by project basis, though, so they're going to be more vague as a rule.

Especially with Rails as rapid prototyping language this is kind of a bad advice IMO. Usually the prototype already will be the base of your application and we both know you will never get rid of all the dept you could build that way

My use of prototype was probably a poor choice. Not sure what is better replacement.

I see where you are coming from but this just does not fit the way a typical rails coder operates.

I've found the google/leveldb[1] source code to be immensely educational, authored by Jeff Dean and Sanjay Ghemawat. A relatively tiny codebase at that, used virtually everywhere and the basis for facebook/rocksdb[2].

[1]: https://github.com/google/leveldb

[2]: https://github.com/facebook/rocksdb

At the top of https://github.com/darius/code-canon I collected a list of other places people have answered this quesion. (The rest of the page is mostly a list of books with worthwhile code, because I'd already written it and because it's harder to think of code outside of books that I can recommend as easily.)

I'm not sure I understand this idea. By "read code" do you mean run the program in your head? As in, "start with main(), follow this loop, go to func()..."? Because if that is the case, then I think it is really debugging not reading. It would be great to debug projects and there are many projects that include unit tests which can help guide engineers along a slow path to greater understanding.

Personally, I like writing code and borrowing ideas from other, better engineers. I also like my code to be clean and without cruft: https://github.com/keithb-/Valley

But I don't even know if I could "read" my code. It's a web app; there isn't a main(), there isn't a loop. In order for someone to read it, they would need to mentally "send a request" which means they need to somehow have the concepts or the context in their mind when they sit down with the source code. I just don't know how that is supposed to help an engineer, regardless of age or experience.

UNIX v6 source code:

http://v6.cuzuco.com/v6.pdf

A tiny C-subset JIT:

https://news.ycombinator.com/item?id=8746054

It might even be controversial to suggest these are examples of "good code" today, because the majority of code I've seen lately seems to be overly verbose and complex. In contrast, these are extremely simple and concise for the amount of functionality they contain. I think this style has unfortunately disappeared over the decades of promoting lowest-common-denominator so-stupid-even-an-illiterate-could-read-it coding styles and enterprise OOP design-pattern bloat-ism, but when I think of "good code", I don't think of Enterprise Java; I think of code which, upon being told what it does, makes you think "wow, I never thought it would be so simple."

I always liked code written by Jersey team - https://github.com/jersey/jersey. It is clean and legible. Though it is Java (not Ruby as your question mentions) IMHO The concept of "Clean code" is language independent.

I always enjoy digging into django-rest-framework [0] when I need to. It is IMHO one of the best idiomatic pieces of python code I have read.

[0] - https://github.com/tomchristie/django-rest-framework/

Upvoted the op. I'm learning Java so if anyone has some particularly good and idiomatic Java (Java 8 preferably) that'd be awesome.

Not Java 8 perse, but I remember getting linked on HN to the source code for the Java collections library: http://grepcode.com/file/repository.grepcode.com/java/root/j...

Had a ton of fun jumping around.

Thanks!

Facebook Presto - See my comment here: https://news.ycombinator.com/item?id=13626109

It strongly depends on what are you looking for. 2 examples: - Git source code is 'almost' perfect. It is a good example. - Symfony source code. Good example of modern web code. Great collaboration and documentation.

This thread from a few years ago is worth a look: https://news.ycombinator.com/item?id=7602237

I'm teaching myself C (pure hobby) and I really liked these codebases:

https://github.com/antirez/kilo

https://github.com/meetecho/janus-gateway

The obvious caveat here is that I have no idea what makes a good C codebase. What I liked in both was I was able to:

compile and run them easily

make tiny changes and observe them easily

read and understand a reasonable portion of them

enjoy the odd comment here and there

At the end of the day, good code is code that solves your problem. Trying to define "good code" without considering the problem will not deliver much punch.

If we're talking a small application, such as a new startup, writing efficient and optimized code is hardly a concern. In this case, good code means flexible, easy-to-change code. The code must make it easy to modify existing features and add new ones.

Compare that to, say, Google's search. The feature isn't evolving much anymore, in terms of functionality, but it needs to be as efficient and optimized as possible, considering the bulk of data it needs to read through, and the immense traffic it gets every second. Sure, you still want flexible code, but speed is critical.

If we're talking an open-source project, the most important part could very well be documentation and ease-of-read. when you have dozens to hundreds of people writing new features, making optimizations, and solving bugs (in their free time and without compensation!), quality of communication takes on a new significance.

These are, of course, simplifications, and the accuracy can be debated (as these situations always have an incredible variety of factors), but the point is that "good code" is not something that can be defined in a vacuum: it can only be defined in terms of the situation at hand.

I personally love xyncro's codes. Their writers are so obsessed with comments, clarity, and consistency across their repositories.

For example, you can see https://github.com/xyncro/freya-optics/blob/master/src/Freya... and can immediately see the clarity and the consistency of the writer.

If you are into ruby/rails already start reading internels instead of docs whem using rails. Rails has a very nice ans clean code base and they do a lot to keep it that way

Without trying to start a flame war, while there is definitely good code in Rails, my personal opinion is that the architecture of Rails is not something you necessarily want to emulate. And this is really the problem when you are new, I think. Many people will love one thing while others will hate it. It's difficult to create an informed opinion.

My advice is actually not so much different than yours. Definitely checkout the Rails internals, but keep a reserved opinion. Then contrast it with other things. From a framework/library perspective look at Sinatra or other web frameworks that that a completely different philosophy. Try to understand the advantages and disadvantages to many approaches.

Again, I want to stress that my intent is not to be critical of Rails (heck it provides the bulk of my paycheck and I'm very grateful it exists!). My intent is really to say not to be so hung up about finding good code, but rather take a long term view of comparing different approaches and thinking through for yourself what you think is good. People who have a different view point than mine, shed light in corners that I won't look. That's always a good thing.

Not ruby, but Javascript.

Have a look at underscore js source:

https://github.com/jashkenas/underscore/blob/master/undersco...

I really loved it! Especially those _ functions are small, concise and easy to understand as well. Very good codebase. (very good example of functional programming concepts)

Thanks!

There's an annotated version available here, which might be a little easier on the eyes: http://underscorejs.org/docs/underscore.html

Underscore's codebase has grown some warts and wrinkles over the years, as optimizations and browser edge cases find their way in ... but the guiding principle is still to keep it as svelte as we can manage.

I highly recommend reading this book: https://www.amazon.com/Refactoring-Ruby-Jay-Fields/dp/032198...

Not only does it contain great code snippets but it also covers repeatable techniques that will ease your life as a ROR programmer immensely.

And there is a nice companion: http://www.poodr.com

Read whatever you find interesting. The point is to familiarize oneself with various ways to implement things. How to know what is good code? Fuck "idiomatic" - usually the code that is simplest and easiest to understand is the best. Towers of obscure abstraction for it's own sake are usually an indicator of poor engineering and poor taste.

I remember reading years ago an article [1] on "Communications of the ACM" that explained why hwpmc's code [2] is an example of beautiful code. The article had a great influence on me; I recommend reading it.

[1] http://cacm.acm.org/magazines/2008/7/5379-kode-vicious-beaut...

[2] http://fxr.watson.org/fxr/source/dev/hwpmc/

If you're working in Rails then I think you can get a lot of benefit from reading/writing some "pure" ruby code. Rails has a lot of its own ways of doing things, so it can be nice to see how to solve problems without using it's help.

For things to read, these books are a little old now but I liked them . https://www.manning.com/books/the-well-grounded-rubyist-seco...

and http://eloquentruby.com/

I really like the (JS) code for the Turing Drawings art app.

https://github.com/maximecb/Turing-Drawings

Just had a brief look over this and have to say I am not a fan. The comments are largely redundant, e.g:

    // Get a reference to the canvas
    canvas = document.getElementById("canvas");

    // Set the canvas size
    canvas.width = 512;
    canvas.height = 512;

And then missing when they could be useful (or a more clear data structure should have been used, e.g. an object with colors as keys):

    var colorMap = [
        255,0  ,0  ,    // Initial symbol color
        0  ,0  ,0  ,    // Black
        255,255,255,    // White
        0  ,255,0  ,    // Green
        0  ,0  ,255,    // Blue
        255,255,0  ,
        0  ,255,255,
        255,0  ,255,
    ];

Not exactly reading code but if you are interested in rails and ruby you might want to checkout:

- Ruby Tapas: https://www.rubytapas.com/ - Destroy all Software: https://www.destroyallsoftware.com/screencasts/catalog - looks like it is a bit more expensive than it used to be, but there is a lot of good stuff in those first 5 seasons.

I second this. Gary Bernhardt is well-respected and I've learned so much from him when I first started doing Ruby and Rails. He has some good ideas about software and he's very good with his tools (vim, zsh, git). He doesn't just cover Ruby. There's some Python in there as well and screencasts on how he uses his tools. You can just subscribe one month and download all the episodes. He already knows that members do this. I do, however, support what he does and have kept my membership.

For Python, check out the Pyramid web framework: https://github.com/Pylons/pyramid

To me, good code not only means smart/savvy logic+architecture, but it also means that it is equally well-documented.

Therefore, for starters,

For scripting language such as Ruby, check out Satish Talim's Ruby tutorials (URL: http://rubylearning.com/satishtalim/tutorial.html)

For compiled language such as Java, check out a recent version of 'Big Java' from your local library.

I've spent the last 4 days reading through the parallel ruby gem [1] and contributing some changes.

It's been a good to refresh my memory about concurrency in Ruby, and Michael Grosser is probably the most responsive maintainer I've ever worked with. Really good reviews and suggestions on my PRs.

[1] https://github.com/grosser/parallel

I've been told by several people that they look to Flask as well written, well designed code that everyone can learn from.

Jquery source is great, how i learned a lot of javascript. Not a rubyist but I'm sure the RoR source is good too!

I found DPDK and FreeBSD's pkg package manager to be very clean and educational.

Reference http://www.dpdk.org and https://github.com/freebsd/pkg

Not Ruby--but pretty all of the code I've seen from Charles H. Moore, the "inventor" of Forth. His code tows that fragile line between self-documentation and brevity. It inspires me, giving me firm reminder that computer code can be Art as much as Science.

Your comment made me curious. Do you have any examples you could link to that you think are good?

Off the cuff, some public examples of his more recent code are contained in ArrayForth, the development environment for the GreenArrays GA144 chip and itself a direct descendant of the original standalone colorForth for PCs: http://www.greenarraychips.com/

NASA's HELAPix, in C:

http://healpix.jpl.nasa.gov/

https://sourceforge.net/projects/healpix/

One of the most important attribute of good code is that it should be easy to extract "How the problem is broken down into smaller problems and how the solutions of the smaller problems are combined to solve the original problem".

Great question. I would say just read the source of whatever libraries you like to use, and let your inner sense of "smell" guide you.

Since you mentioned Ruby, start by reading Rails itself. For all the hate people have for it, I believe it really is a solid exemplar of above-average code. Reading through the ActiveRecord source just after Rails 3, and seeing the way it was semantically organized by feature via included modules, was an inspiring moment for me as a coder. It was probably the first time I'd seen code that was simultaneously practical, modular, and readable.

You should never trust people's statements about what techniques are good and bad in a language. It's called "code smell" because you can judge it for yourself without having others dictate a judgment for you. Just like you can decide for yourself whether something smells bad or good.

The kickstarter app is open source and has amazing code quality: https://github.com/kickstarter/ios-oss

Facebook's open source C++11 library: https://github.com/facebook/folly

https://github.com/discourse/discourse

https://github.com/niklasso/minisat

Your post inspired me to inspect element to see the front-end code on HN only to find out the layout is all tables...

Donald Knuth, "Literate Programming", tangle/weave (https://en.wikipedia.org/wiki/Literate_programming).

The same source can produce compilable code, or formatted comments.

Literate programming is certainly a very neat idea. I wonder if he would consider IPython / Jupyter notebooks an approximation of it?

in terms of rails code https://github.com/coderwall coderwall is a well used/known blogging site for devs

Check out the WASTE text API, its written in C and its very nicely done.

Any code that, when looking at it, you know exactly what it does ...

For C++, I think Jules Storer's code might be worth a look.

https://github.com/bottlepy/bottle

A single file running both in python 2.7 and 3.

Just Nothing -- ^ Haskell

Well speaking Java 8, this java to html library is clean, mean and tight: https://j2html.com

Why, my own of course! Peewee[1] is a lightweight ORM, and Huey[2] is a task queue.

[1]: https://github.com/coleifer/peewee

[2]: https://github.com/coleifer/huey

I was very impressed with the sorce code to this application: http://florence.sourceforge.net/english.html

Nothing groundbreaking, just basic OOP code, but it was unique in that I started reading the source code and understood it quickly.

Is the source available online anywhere? I can't see anything of the sort on that page.

Here it is: https://sourceforge.net/p/florence/code/ci/master/tree/

I also found xpra's code to be easy reading. Also very unexceptional. I read it and I'm like "meh", but I understand it. And that is the important part!

http://xpra.org/trac/wiki/Source

Sorry, I don't have a link to some beautiful code.

I assume that as a developer you are interested in solving (business?) problems through the act of writing software?

It isn't much different than being a painter I guess. To be able to be a good painter (or to be considered a good painter) you first need to have a good grasp on how to use the brush and how to handle paint (e.g. oil paint), i.e. you need to learn the technique. The more versed you become with the technique the better you will become at painting, or, over time you will become better at painting what you intent to paint, to paint what's in your minds-eye because you don't have to think about the brush and paint anymore.

When it comes to software you first need to have a good grasp on programming. This means you will need to spend time practising the act of programming. Using two languages that are very different from each other might be good. E.g. learn an imperative and functional language. In your case this might e.g. Ruby and Lisp. Your programs will need to interact with other systems so you probably need to learn about operating systems, databases, queues, networking, etc. You probably don't have to be an expert in everything but being a good all-rounder will certainly be beneficial.

Over time you will see that it becomes easier to think in solutions of the bat rather than focusing on how you're going to solve a problem. This is basically what is being referred to as experience.

So, to be a good developer you need to put in the effort and you need to put in the time. There usually aren't any short cuts. I've been doing this professionally for over 20 years and I'm still learning every day.

"So you're an architect eh, and you want to study existing architecture to see how it was built, eh, to get better? Well you can't. Sorry, I don't have any buildings or architectural blueprints ready for you. That's not how you learn. You need to study architecture, not look at buildings and how they're built. There's no shortcuts here. I've been an architect for over 20 years and I've never looked at a building."

OP says "I keep reading on HN that I'm order to become a better developer I need to write code everyday, and more importantly read other people's code."

It hardly sounds like he is looking for a shortcut

Reply on news.ycombinator.com