Hacker News new | past | comments | ask | show | jobs | submit login
One Way to Improve Your Coding (changelog.com)
362 points by ingve on Dec 19, 2016 | hide | past | web | favorite | 116 comments

A lot of people will recommend reading great code -- well known open-source libraries etc. That's good, but one thing I think is useful is to read your dependencies. Then you can get a better picture of what "regular" code is like. Most popular libraries are not great to read because they are often very abstract, or they use so much helper code that it's hard to see what's actually going on. But fairly small libraries are usually easy to understand and usually are also fairly straightforward, but by reading code you'll be able to put yourself in the shoes of someone who will be reading your code one day, which is the most important things to keep in mind.

I'm mainly a front-end developer, and the nice thing about the npm/node ecosystem is all of your dependencies are right there in node_modules, so feel free to read them to see how they work, or why something isn't doing what you expect -- you can even add debugger statements or console.logs.

In some ecosystems this is harder because you might have to hunt for the source, or only have headers. For example in ruby, use bundle show my_dependecy to see where the code is stored.

I certainly agree with this sentiment (and the author's words "Read code that you can actually grok"). As a younger programmer, I tried to get into reading the source code for Flask and learned pretty much nothing.

The thing that has seemed to have the most effect for me (of course, this may not necessarily be effective for everyone) is refactoring or even completely rewriting my side projects after/near finishing them. It's a little bit maddening, since I would rather move forward and build new features or start a new project, but the exercise is really helpful. It forces me to take a step back, look at everything I've done, and figure out where I could have done something better. Then, hopefully at least, when I'm in a similar spot in the future I'll be able to think ahead better. In fact, "thinking ahead" might be the most valuable skill for a programmer to have, and I don't really see how reading code can help with that. All of their design decisions have been made by the time you read the code, and it's really difficult, especially for a junior developer, to actually consider how and why those decisions were made.

As a (mostly) front-end developer, I agree that reading some of the code in your node_modules can be enlightening. Sometimes in a good way, sometimes in a bad way.

There have been times when I've dug into a module when something wasn't behaving properly, and was shocked at how bad the code was. It's not as if I included it intentionally - it's usually a dependency of a dependency of a dependency. All the same, it was garbage that I'd been shipping as part of my application.

Your point still stands, though. Having the code where it's easy to find and read is helpful. And reading bad code can be as helpful as reading good code. Sometimes, the trauma caused by seeing some atrocious code can improve your habits more quickly than reading beautiful code. :)

Also, at the OS level, there are entire projects built around just understanding the dependencies in the Operating System and applying minimalism to try and get to a state of (relatively) simple, known dependencies.

One of my favorites is Rob Landley's Aboriginal Linux:


I highly recommend his blogs if you're interested.

Great suggestion. It's great because you have context (you know what the input/output is) so the learning curve is flatter. Anytime I've done it, it's been a confidence booster. I always feel like the dependencies I use are built by genius coders who are much better than me. When I inspect the source I am reminded that it's just the same ole' code as I would write, but of course better documented and tested :)

It's not really any harder to modify the dependencies in Ruby (or Python, or I'd guess most other dynamic languages). They're usually all stored deep in a subdirectory, but a little find-fu typically gives them up quickly enough. I agree that people should be more willing to dig underneath the covers and see how the code they depend on handles things.

Very good. Libraries are what everybody relies on, but IMHO gets to little attention and appreciation.

I'm going to be "that guy" in the comments section this time, largely because I feel like I've been seeing this more recently and I've had to fix it myself:

I don't really get why it seems to be a "thing" recently for websites to have low-contrast text colors. This is at least the second time in a week I've seen light gray text on white background, and to not strain my eyes I went into the CSS for the website and fixed it myself by just making the text black. Another website was even lighter gray than this one, and it was very difficult to actually read the words. I'm honestly curious as to what it is designers see about the light gray text on white which is appealing to them. It feels like they should be straining to read it just as much as myself, but it still makes it onto the production website. If the person/people who have control over this end up reading this, I implore you to just change your "ol, p, ul" color CSS attribute to "color: black" or some such.

Otherwise: I like the idea of asking developers to read code. It is actually a wonderful way to learn good habits. I still have (good, hopefully) coding habits that I can attribute back to reading Half-Life 2's Source engine code a long time ago.

I've been a UX designer for 10 years and I can tell you why. (Or at least why from point of view.)

It's a deprecated design practice to make font rendering looks smoother in a world where retina screens were not ubiquitous. Back in the old days (so like 3 years ago) before the majority of screens were 'retina' (aka you can't see the pixels at normal viewing distances) fonts always rendered with jagged edges. Turning down the contrast between a font and its background is effective in reducing this effect. It reduces the contrast, it's a very straightforward mechanic. Obviously, this is moot now with razor font rendering on retina screens. And if you do it too much, you risk accessibility problems.

The nonsense about black on a white background being too harsh because of eye strain is exactly that: nonsense. If you wanted to reduce eye strain, you'd dial down the brightness of the actual background, often seen in "nightmode" options offered in various UI. (Come to think of it, that would be hilarious if you hit "nightmode" and it just lightened the text, making the overall screen even brighter.)

> Back in the old days (so like 3 years ago) before the majority of screens were 'retina'

I can assure you that the majority of the worlds screens are not retinas. maybe the majority of screens owned by experienced developers in the US (very high incomes + cheap electronics) are retinas. Maybe. But in the world? Absolutely not.

> Back in the old days (so like 3 years ago) before the majority of screens were 'retina' (aka you can't see the pixels at normal viewing distances) fonts always rendered with jagged edges. Turning down the contrast between a font and its background is effective in reducing this effect.

Interesting perspective. I was a designer a while back and every designer I've ever worked with has never done this for the reason you state. In fact they always have the latest and greatest monitors and resolutions so they'd never see the issue anyway. They always told me it was "because it looked better".

I always fought to change it and got it changed in every case but the difference in perspective is interesting so I thought I'd chime in.

That's an interesting point of view! As a UX designer veteran, you must know these numbers better than most of us here, do you know how ubiquitous retina screen are?

On desktop, the Firefox Hardware report [1] tends to show that they the most common resolutions are 1366 * 768 and 1920 * 1080, this unfortunately doesn't tell us if those are retina screens or not, but from [2] it seems that we're talking about at most 17% as a 'retina' display would report as 1920 * 1080

[1] https://metrics.mozilla.com/firefox-hardware-report/

[2] https://news.ycombinator.com/item?id=13184022

And I've lost track of the web UIs that pretend that everyone has and will game the web page 1920 pixels of width (while writing this, I'm glaring at JIRA in 1200x1920, portrait mode.)

UHD is not the only HiDPI/retina resolution. My 15" MacBook Pro has a hardware pixel resolution of 2880x1800 but reports "CSS pixels" of 1440x900. The report being from Firefox, all the iOS devices with retina displays aren't represented at all. I don't know how ubiquitous HiDPI displays are on Android devices but my hunch is most smartphones sold in the U.S. and Europe have them.

There's indication that 00/FF contrast can be problematic, especially for dyslexics [1].

The ridiculous part is the amount the contrast is often toned down as a result. No one benefits from a sea of grey on grey bordering on unusable.

[1] http://www.bdadyslexia.org.uk/dyslexic/eyes-and-dyslexia

That's interesting, I'd never even thought about something like that. Thanks for responding with that information.

Is this still something that gets taught? Or do you think that these sites are being made by people who were taught that a number of years ago and haven't taken the time to learn how to interact with monitors in a post-retina/high-dpi world? Or has it become some kind of "cult" knowledge that gets repeated by people who aren't aware of the real reasoning behind why it was done back then?

Also interesting to learn white-on-black eye strain is nonsense. Another comment mentioned that it probably looks better to have dark gray because true blacks are rare, is that accurate?

Who knows? Maybe the contrast on their monitor hasn't been set correctly.

Their text to background colour ratio is 4.6 which is really not that bad with their 18px font-size.

That being said, I'm not a fan of grey on white either.

Yeah, it's actually WCAG double-A compliant.

Agree in general though, more & more I end up tweaking site's font-size/line-height/contrast to bring it back to normality.

From my limited exposure to designers, I've learned that they think lower contrast strains reader's eyes less than high contrast does. Black on white is thought to be too striking to read comfortably.

Here is a post from 2012 explaining why it's important to use a dark grey instead of a pure black: https://ianstormtaylor.com/design-tip-never-use-black

And I agree. Pure black often looks bad.

Light gray is even worse.

Fair enough! But if webpages that did "black on white"-style text, like a book, and just emulated what books look like, (not-really black text and not-really white background) I'd be 100% ok with that. Modifying a webpage to not have light gray text is much easier to type "0" for the color than to type out an exact, least-eye-strain gray. I'd much prefer if designers put in the least-eye-strain gray for me :)

I can add my anec-data: I find it really hard to read white text on any dark background, black being obviously the worst.

I also find pure white with pure black really straining on my eyes. I hate the trails of lines I get reading bright text on dark backgrounds, or with really high-contrast colours generally.

Like the parent(or grandparent?), I've edited CSS for web pages. I've got a chrome extension called change colors installed, which has shortcuts for override-colours-by-domain and on-this-page-only. Really handy.

I wonder if this rule of thumb will change when OLEDs are most common displays.

It seems like it might be worth taking advantage of OLEDs ability to do unlit black.

I like this characteristic of OLEDs. When I'm reading a book on my phone in low light I like to set the background to black and text to white. It significantly lowers the light output of the screen in that scenario compared to a traditional LCD. That factor alone made me prefer my Galaxy S5 over my gen1 kindle fire for reading despite the screen size.

> Black on white is thought to be too striking to read comfortably.

It is, but (very) dark gray text on a (very) dark gray background is fine. This light gray on white thing is just nonsense.

I recall a blog post by Ian Storm Taylor [0] that suggested it from the perspective of a painter. Not sure how well it applies to screens, but it's definetly not a thoughtless move to use #222 for your fonts.

0: https://ianstormtaylor.com/design-tip-never-use-black

This site[1] says it's because people conflate content with illustration. It also cites Hacker News as an offender (although looking at their screenshot to what I'm seeing, I think it was "fixed")

[1] http://contrastrebellion.com/

The low contrast is on self-posts (Ask HN, etc). Aside from being more difficult to read, I always get an instant "negative" vibe when I see them because it looks like they've been heavily downvoted.

In an ironic twist, the "TWEET" link toward the bottom of the page has atrociously-terrible contrast against the dark background.

> I don't really get why it seems to be a "thing" recently for websites to have low-contrast text colors.

It doesn't need to be any more complex than "designers think it looks nice". Black text obviously has a better contrast but I bet it doesn't look as good.

There are many darker gray options to pick from though... I'm not as good as I was when I was younger, so fine detail is hard... I'm using a 40" 4K display at native resolution, and most of the websites I use I bump between 125 and 150% to be readable. These tiny devices with really tiny fonts kill me... I don't use the FB app in particular, because even with the accessibility settings turned all the way up, I can't read the damned thing on my phone. Really wish FB would fix this, but there are other web offenders too.

I get design is important, but it should NEVER be at the cost of removing usability.

I agree, I've found myself tweaking site CSS often lately as well. To some designers' argument that there's no such thing as true black I say that this is a limitation, not an ideal. https://bestmotherfucking.website/#grey-text

Were my JS fundamentals a little stronger, I'd work on a browser add-on to detect low-contrast body text and improve it automatically.

I'll bet $100 that in this instance, it was just an impromptu design decision. He liked the way it looked, it contrasted nicely with the headings and that's it.

The most obvious way to improve your coding is to write more code.

This is a bit too simple: writing more of the same, in the same style, usually won't cut it and unfortunately I've seen people being stuck like that for years: always producing more code, without any improvement whatsoever and instead just repeating the same mistakes. Once those mistakes become a habit they are extra hard to get rid of. So actually writing more code can be worse :]

What you really should be doing is write more and from time to time different code, combined with learning through either reading others' or continuously asking yourself 'how can I improve this' followed by e.g. a trip to StackOverflow to find out.

Write more and reflect on what you've written. I've come to have a dev diary where I reflect on what I did the past day/week, and note things I ran across that did/didn't work out so well, and why.

That said, if all you're doing is greenfield development I don't think it's actually possible to improve without third party input. A major goal of good code is maintainability, and that can only actually be known in hindsight.

Note that the author didn't claim that it was the best way, or that it might not have drawbacks, just that it's the most obvious.

>This is a bit too simple: writing more of the same, in the same style

I think the author means there's a correlation between the amount of code one writes and their progress.

For a more complete view, there's the often cited article The Role of Deliberate Practice in the Acquisition of Expert Performance[0] where the authors make a point that it's not just practice that makes perfect, but deliberate practice. They set to find and explain patterns exceptional people follow.

What you're talking about is what someone who says they have 20 years of experience but, in reality, they have 6 months of experience they've been repeating 40 times.

[0]: http://projects.ict.usc.edu/itw/gel/EricssonDeliberatePracti...

Depends what you are wanting to achieve, to be honest. Writing the same code can help make you faster at writing that code. This can be annoying to people who are higher level coders, but the reality is that intrinsic quality of code is easy to complain about, but hard to model the importance of. In large because its importance is quite low.

That is, if what they are writing works, despite having what could be seen as mistakes to a more disciplined practitioner, then what is the problem?

Consider, someone that has put together Ikea cabinets every week for the past year is probably hella fast at it by now. Can they replace a carpenter? Doubt it. Are they bad at what they do? Doubt it.

That is, if what they are writing works,

You make a good point, but imo in real life there is more nuance to it than just works/doesn't work. Which again I've seen with the same collegues: the software works, sort of, yes. Despite some annoyances and known bugs and corresponding workarounds it does what it's supposed to do. But it's oh so brittle. So while you could argue that it works so there is no problem, in fact there is: on every single change which has to be made half of the software falls apart and it takes insane amounts of patching to hold things together. Sure, afterwards it works again, but adding more of the same code, no matter how fast it was written, made things surely not better. I admit this is of course like the worst example and I'm sure there are indeed occasions where the code quality doesn't have that much of an impact. For instance especially in small applications/tools/extensions this is true.

I completely agree that it is complicated. The whole debate is strewn with staw men, which does little to help move things along.

Still, fun to think about. If you know of any studies, I'm interested.

I want to recommend everyone who sit infront of a screen for several hours per day to invest a few hundred dollars extra on the monitor. The extra contrast makes a huge difference.

Ditto. I bought a 34" 3440x1440 a few years ago - the Dell U3415W. Not long after I made the switch to Visual Studio and C# about a year ago, I bought another - the Acer Predator X34, and took the Dell to work. They're just awesome for programming, as well as other purposes if or when time avails.

Exactly. It's like claiming that because I drive to work every day I can eventually become a racecar driver.

This is a good reason why becoming a "polyglot" probably does more good than harm. Many languages are often better suited to different programming styles or paradigms or problem sets or environments than other languages; learning a new language can help better understand a new concept, thus improving one's ability in general across all languages.

Exactly. I've found that my development skills leaped to another level when I tried out some functional languages. Since then my code is more readable, more concise and has less side-effects. Now looking for the next step.

When I was teaching at General Assembly, I always tried to encourage students to read more code.

Could you imagine someone studying writing in college without reading a TON of books, analyzing, and critiquing the writing other others? Where all they did was simply write, but never read anything from great writers? No, clearly not.

Yet, that's what I see most new programmers doing. There's an urge to do it all on their own, without reading the works of others, and that is a surefire way to setup for failure.

It isn't necessarily analogous to compare the study of writing in college to that of learning to program. For one, by the time you are in college, you have been speaking, reading, and analyzing (via communication) your native language for ~15 years. Because we already have such a vast foundation to work from, we can venture into deeper parts of the language and meaning and interpreting how authors use it to create meaning.

I think programming is more analogous to learning a new language. Now I can imagine studying Spanish (a non-native language for me) without reading a ton of books, and analyzing and critiquing other Spanish writers, because I simply can't and it isn't that beneficial - from the beginning - to start that without have some foundation to work from. It is only after you learn some vocabulary, grammar, semantics, sentence structure and some cultural significance, that you venture into analyzing and critiquing their writing.

I think for beginner programmers, it isn't supremely beneficial to read a bunch of others code, because you don't really know what is good and what isn't or even what to really look for. However, when a programmer creeps into the intermediate level of things, I think reading other's code becomes amazing beneficial, because from that foundation, you can understand, analyze, critique, and maybe most importantly, internalize what that programmer is really trying to achieve and how you can use their methods going forward.

Now in reality, we don't really know the point we hit that intermediate level, and we will inevitably be reading other's code at the beginner level. I think it's just a matter of shifting the weight that we put on reading other's code as we mature as programmers.

Reading code becomes beneficial at the moment your biggest concern is no longer "does the application work?" but "how does the application work?" I ceased to be a beginner when I became confidant that I could make something work. My concerns ceased to be "can I make this work?" and became "is there a better way to make this work?" Confidence to answer the former question is gained through writing code. Understanding to answer the latter question is gained through reading code.

The other side to it is that you'll rarely be writing completely new code from scratch in the majority of development positions (especially as a new developer). Being able to dive into someone else's code, think about it, an add something to it, is probably more important on a day-to-day basis than being able to create something from scratch.

I think programming is more analogous to learning a new language.

I think your analogy is spot on, and yet reinforces the OP's point - one of the best ways to learn a new language is to read a lot of good writing in that language - you absorb idioms, subtle points of grammar, and vocabulary, all of which would be a struggle if you just try to focus on the basics or use a grammar textbook to help. Immersion in the right environment is by far the best way to learn.

The current situation with most people programming is that they spend years looking at code written by other beginners (stackoverflow, tutorial articles), and very little time studying real production code written by people who have been doing it for a long time. That is as the OP points out a huge mistake and one it takes many people decades to remedy if they ever do. It's like trying to learn a language by putting 30 beginners in a room with a textbook and making them speak to each other.

I'd honestly recommend absolute beginners to spend at least some time reading simple code by someone they admire, if only to demistify the process, and make them realise it is not as complex as they fear. Beginners almost never do this though.

However, it's not really a story you can read through end to end so often as a choose your own adventure with thousands of routes to move through. Though there are smaller projects you can work through and better, or less organized structures... it depends.

I'm not sure this is a fair comparison, because books are written to be read, but code is (usually) written to be executed. As much as we all agree that code readability is important, the simple fact of the matter is that executability matters a helluva lot more. We're paid to write code that executes, and many people stop there.

The result is that there is a lot of code out there that executes just fine but is completely terrible to read, and I wouldn't advise learning from. And the problem is, especially for beginners, it's difficult to determine which is which.

Add to this the fact that code changes over time, in more ways than one.

1. It physically changes, i.e. we commit changes to it, so a codebase that is well written today may be dramatically changed tomorrow.

2. The context changes, i.e. the circumstances that make one tradeoff better than another change all the time, and if the context isn't captured effectively, it's difficult to understand when good decisions change to bad ones.

3. The language changes, i.e. new versions or even entirely new languages come out which fix mistakes in old versions or languages, so good code today may be difficult to learn from in the future if the language is no longer well understood.

We need more collections of repositories that are agreed upon as "good quality" that everybody agrees are worth reading and learning from.

Code is primarily for communicating between programmers, if it were mostly meant to be executed it would just be object files.

Being a great coder means being adept at reading code however its structured. Reading unclear code is important because it helps you avoid making the same mistakes... it's also an important skill in practice: You will often encounter unclear code and have to understand it.

The idea that there is one true good form is a misconception often held by novices. An expert should be able to read and write in a multitude of styles so that they can conform to whatever codebase they're working on and apply the best practices within that context.

These are all great points, and I'm realising now I have missed the point a little. Reading arbitrary code is good, because you learn something regardless of whether the code is "good" or "bad" -- you learn how to understand more styles of code, and which patterns tend to be easy to understand and which tend to be hard. I guess the part that was tripping me up is that you shouldn't necessarily try to emulate all code you read.

One point not covered by the article is how reading real world code will also help set realistic expectations, especially if you are a relative newbie. The truth is that there is a lot of code in the world, even in popular frameworks and libraries, which does its job but which does so in clunky or unreadable ways. I don't blame this on the developers, on the contrary it's my experience that any codebase will develop a number of FIXMEs and TODOs over time because the initial design very rarely matches the final design and because there is not a business case for making everything shine. Perfect code is a noble goal but prohibitively expensive to implement.

This is a nice lesson for a novice programmer to let sink in. That software is written by humans. Mostly clever people but not infallible. And subject to all kinds of tradeoffs. They call it computer science at university, but most of the time we are craftsmen working on buildings evolving as we go.

I recall my personal eureka moment in this regard. 2001, final year of university, writing Java code for my thesis. Downloaded the source code for the official Java APIs, I think it was, to better understand how they worked. I was genuinely surprised by the amount of critical comments and "fix this" comments strewn throughout the code. It was a great learning experience and took the pressure off my shoulders to be "perfect".

Good point. I'm always thinking my code is crap (it is) and inferior. But reading other code has made me realize that others code often has its warts too.

The key is seeing others code warts (or lack of them) makes you identify your own warts.

As a self taught "make things that do what I want" sort of a coder, I am eternally worried about the things I don't know. Each solution is the best I could come up with - but I'm confident it's still probably shit.

So I often just wish I had someone to talk to about what i probably fucked up, or why it was a bad idea. For now my code is just littered with "I did x because y but I'm not sure if z was better or if there's another option I couldn't see".

Agree with this. I know there are sites that compete for minimum key strokes to compete a task in, say, vim -- is there anything similar for code? Is there somewhere people can post code and others can suggest ways to do it better? I think this would be extremely helpful.

Find someone to trade code review with?

Turns out all the real devs are kinda busy and don't have a couple hours a week to help all of us people who make their lives miserable..

They don't really have to be above your level for the exercise to be valuable.

To save anyone the trouble: the way is supposedly to read code.

Here's a counterpoint I find pretty convincing: http://www.gigamonkeys.com/code-reading/

Here's a brief excerpt:

> 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.

>Seibel: I’m thinking of the preface to SICP, where it says, “programs must be written for people to read and only incidentally for machines to execute.” But it seems the reality you just described is that in fact, most programs are written for machines to execute and only incidentally, if at all, for people to read.

> Abelson: Well, I think they start out for people to read, because there’s some idea there. You explain stuff. That’s a little bit of what we have in the book. There are some fairly significant programs in the book, like the compiler. And that’s partly because we think the easiest way to explain what it’s doing is to express that in code.

How do you read a novel? Start at the first page. How do you read a codebase? Uhh...

Start at the init() function?

Any recommendations for an open-source Java codebase to read that makes good use of the Java 8 concurrency features? Currently in a new job and struggling with an undocumented, uncommented codebase containing streams, rxjava, executors and futures. Could do with a different, hopefully documented, take on Java concurrency.

Another good technique for understanding other people's code is to attach a debugger.

Find an interesting spot in the code that you'd like to examine more closely and set a breakpoint there, looking up the stack to see who called this function and who called them and so forth.

Can anyone recommend good tools for reading code? I find github.com to be very klunky for this purpose, and even emacs/vim make the task much more troublesome than it could be. Is there such a thing as a "read-only IDE" anywhere out there? (Ideally features would include click-to-definition, navigate back and forth, add bookmarks and annotations.)

This is a great idea, if it doesn't already exist.

Edit: On a little further reflection, it would be really fun to build. I can imagine a site called something like readgithub.org, which is a dedicated site for reading the code hosted in github repositories. You could start focusing on projects in one language only.

I recently came across something like that for opensource Java code, called `grepcode`:


It supports quite a big number of Java code repositories it seems.

Edit: Also sourcegraph (linked in a link in a sibling post) does something similar:


Check out this recent comment and discussion. User TeMPOraL describes a similar wish and gets many nice responses.


thank you! that is a very helpful thread

this chrome extension, octotree https://goo.gl/BZRqop, is very helpful for reading code on github. Reading github is how I started learning how repos are structured and how to read other people's code when I was early in my cs degree.

This is awesome, thanks

Coming from Visual Studio, my impression is that a proper IDE should do all those things you mentioned. (minus annotations, but that's what comments are for)

I am curious as to why you would want a read-only IDE though. I'd like to see what would be different if the IDE's focus was for reading a large code base rather than writing one.

I would generally agree an IDE should be the best place, but I've had trouble in practice. Maybe I haven't leaned on those features enough? My trouble with a brand new codebase (framework, language, or library) is sussing out separation of concerns (usually split between files/functions/modules) and flow of code. An IDE should definitely help navigate those things (sometimes you need to actually run the code and look in a debugger).

One reason a website might be more handy is skimming codebases you don't actually intend to build and compile. I do this to new projects all the time to stuff I see here (generally on GitHub). I'll also often look into the cPython codebase because I use Python, but it's very rare I have the need to download and build it.

You're right, of course. I guess what I'm really longing for is ease-of-use and ease-of-setup. For ease-of-use, the default action is navigation (just like reading a web page) so that I can drill-down and mentally execute code not unlike being in a debugger. For ease-of-setup, I don't necessarily want to clone something, create tag files, and possibly install a language mode... I just want to read.

Perhaps this seems a bit lazy, but I think of reading code as similar to reading books or articles: not everything is worth the same level of investment. Yes, some things I want to really get into, and get dirty running (or writing) tests, refactoring, and commenting. Other things I want to just (passively) read or even skim.

I feel like a full IDE, or the recommendations in the parent article, lean toward the in-depth study that I don't find appropriate for every task.

(It's been 20 years since I last used Visual Studio, so my understanding of its capabilities is obviously dated.)

> Perhaps this seems a bit lazy, but I think of reading code as similar to reading books or articles: not everything is worth the same level of investment.

The point of reading code is to understand it. How to read code efficiently depends also on language and coding style. Which would require full blown IDEs just for proper code navigation. And honestly: If setting up an IDE for the language you want to read is too much trouble, programming is and therefore there is no need to read code at all.

EDIT: When I review code that reads like a book, the programmer immediately makes into my hall of fame. Such code is so rare that its coders should be paid their weight in gold - per hour.

> The point of reading code is to understand it.

There are varying levels of understanding (or desires to understand something). I use Python a lot. For a lot of the language and libraries my understanding is superficial; dicts have key/values, lists are ordered and mutable. As I use it more I'll dig more into specific parts as needed; how do lookups happen for a dict, how are lists allocated? If I downloaded cPython and read it top to bottom trying to understand everything I likely wouldn't retain those relevant parts I need. I also don't need to download and build all of cPython to answer most of those questions.

Also, new projects get posted all of the time here. I'm curious about other languages and frameworks not because I need to know and understand everything, but I'm curious how I can approach something in a new way. It'd be nice to have a browsable interface on the web.

Your argument here sounds like it would be against having syntax highlighting in anything that's not an IDE (like GitHub) because if you cared enough, just download it and open it in an IDE.

[deliberately responding out of order]

> Your argument here sounds like it would be against having syntax highlighting

No, but syntax highlighting is just something that helps parsing a single page. I'm talking about "show documentation for function/var/whatever under cursor", "jump to definition", etc...

> There are varying levels of understanding (or desires to understand something). I use Python a lot. For a lot of the language and libraries my understanding is superficial; dicts have key/values, lists are ordered and mutable. As I use it more I'll dig ....

That "digging" is what I am talking about. Code is rarely read sequentially; it's reading docs for functions/classes/vars, jumping to definitions and finding call-sites. To do this, you need a very good understanding of the target language by the "viewer"-tool. Thus: You need an IDE for proper code reading. And probably still a good grasp on /usr/bin/find for those things your IDE cannot help you with.

I still think I have different (lighter) needs when skimming code online. I do think an IDE would be the ideal solution. What I saw the parent looking for is a middle-ground, maybe you have something like VSCode, but cull out compilation, editing, and debugging to it loads more quickly.

> That "digging" is what I am talking about.

Those are examples I gave are where I don't need to navigate the codebase. The answer is in a single file. So far I manage with the current web interfaces. Locally, I'd use grep and vi. GitHub works ok, but it's hard (but possible) to compare versions or jump between files. Using Google Code or SourceForge I have trouble finding the "Browse" button to even find the code.

You can have all these in emacs and (probably) vim, as long as you configure them properly for the specific language bindings (for jump to definition). For bookmarks, there's functionality in both, same for annotations (IIRC you can use org-mode to create annotations, for vim not sure what but definitely there is something)

Why is vim more troublesome than it could be? With Nerdtree and Fzf/Ag plugins (or ctrl-P) I can't imagine how much easier it could get.

I thought sourcegraph did something sort of like this.

So this is a good place to list really nice codebases. sqlite is a fantastic piece of source code, totally worth reading.

For Python, I really like reading Kenneth Reitz' code. For example the Requests library is pretty good reading [0]. When reading code, I like to have the documentation handy as well [1].

The Django project is also good reading. [2], [3]

[0] - Requests code: https://github.com/kennethreitz/requests

[1] - Requests documentation: http://docs.python-requests.org/en/master/

[2] - Django code: https://github.com/django/django

[3] - Django documentation: https://docs.djangoproject.com/en/1.10/

Django does have some really clean code and it is very easy to navigate. I feel like I only grokked Django after I started going through its internals.

I also highly recommend giving Tornado[0] and Bottle[1] a read. Outside of the the web stuff, Sqlalchemy[2] is good

[0] - https://github.com/tornadoweb/tornado [1] - https://github.com/bottlepy/bottle [2] - https://github.com/zzzeek/sqlalchemy

Quake 3 is my favorite, to go look for inspiration when stuck. And I'm pretty far removed from game development.

It's a bit old, of course, but TeX: The Program is still a fascinating read because of the exceptional attention that Knuth has paid to exposition, especially for a program that size. Besides, TeX is still being used after almost 40 years, so it's inarguable that Knuth did some things right.


For historical kicks, it's hard to beat Lion's Commentary on UNIX 6th Edition: https://en.wikipedia.org/wiki/Lions'_Commentary_on_UNIX_6th_...

This is one thing I need to do more often. I came from a school and industry segment (.Net) that very highly discourages reading other people's code, and even years later I feel guilty trying to read jQuery's source when I run into a weird edge case.

Is there projects out there that are easy for beginner code readers to grok? I've tried reading libraries you've all heard of, but even after an hour of jumping between files I still have trouble getting a view-from-10000-feet picture of how the project works.

Keep in mind that part of what makes reading code beneficial is that it's not necessarily easy- in fact, it's often rather hard! The benefit is developing a set of "mental heuristics" to figure out what parts of a codebase are useful, so that when you have to dig through someone else's code you can figure it out just a little bit faster.

That said, here are a couple suggestions. I'm not sure what you use other than C# (and Javascript?) so I'm just gonna link things from several languages.

redis-rb [1] is the 'official' Ruby client for redis. (For that matter, I've always heard that redis itself [2] is a good example of C code.) React's source [3] is rather difficult to figure out, but the team recently released a codebase overview [4] which might help. Alternatively, preact [5] is relatively straightforward, and IMO is a good example of structuring an ES6 codebase.

Rails [6] is ridiculously huge, and has established a bunch of its own conventions for file loading, but on the flip-side it is extremely well documented. To take a single bite of the elephant, take a look at its ActiveJob [7] sub-framework.

1: https://github.com/redis/redis-rb

2: https://github.com/antirez/redis

3: https://github.com/facebook/react

4: https://facebook.github.io/react/contributing/codebase-overv...

5: https://github.com/developit/preact

6: https://github.com/rails/rails

7: https://github.com/rails/rails/tree/master/activejob

Rails codebase tends to have a problem of only containing information about how something is supposed to be used and very little about how things fit together or why particular choices where made.

Thank you! I'll have to look at these later on!

Still feels like stealing, but that's my problem :)

Stolen knowledge is best knowledge. Then dazzle everyone with how smart you are!

Oh, and don't be afraid to do git blame on some particularly hairy piece of code and see how it came to be. Often commit messages has a lot of information. If you are using Emacs, vc-region-history is pure gold, I don't know how to produce that view from the command line.

This is a great recommendation, at least for middling programmers like myself. Every time I've been forced to dive into a third party library to understand how a certain case is handled or how a poorly documented feature works I've come out more knowledgable about the language, what I'm working on, and programming in general. The key of course is to really try to understand what's happening, not just peruse casually.

What I missed in the article is a suggestion to also try and fix the problems you find in the code. Creating patches that macthes the style of a project, submitting them and handling the communication that usually follows including update to the patch until accepted is a good learning process too. And then you've also helped the project. Win win win win.

And finally. Remember to go back to your own code. You'll be amazed at how many warts you suddenly see. Things to improve, fix, change and cleanup.

It doesn't look like a good approach to me. There are a lot of bad code out there and the only thing you can learn from it is how to write bad code.

The important things are the right mindset, the ability to reason about code quality, and good set of more concrete skills: algorithms and data-structures, beginner level understanding of different programming paradigms and their applications (class-based OOP, prototype based OOP, FP, you'll get a deeper understanding of one or several of these approaches when you start using some specific language), particular language features, idioms and libraries which can help you solve real problems.

Most of these things can't be deducted from reading code. Some of them can but again you have to read good code. The suggestion to just read a code of the thing you use is bad. You have to find a mentor who can direct you to the idiomatic and effective code.

The best thing you can do after getting used to the right way is to solve some problems and then improve your own code until it shines. Then you can read a code of the libraries you use and maybe improve it.

"There are a lot of bad code out there and the only thing you can learn from it is how to write bad code."

Oh, I dunno. I've done it a bit and found value in it.

I spend big chunks of time writing customizations or extensions for WordPress plugins. It's not exactly a fun way to make a buck but it is easy to be better than most folks writing for WP and I work remote from a tourist town... but my point is that I have read a shit ton of really bad code. If you think that all it's done has made me able to write bad code, fair enough... I'm not exactly solving difficult problems.

But I still feel that it's good advice to read other peoples' code.

The benefits of knowing that you can do better than some folks aside, being frustrated by some poorly documented code that is difficult to reason about is a really great way to understand why you shouldn't write stuff like that, and the various ways in which things can get messy.

It's not the best thing in the world, and I suppose that on some level its struggling against rather than reading this code which is the real benefit.

But I agree with Stephen King when he writes in _on Writing_ that there is value to writers in reading some bad novels.

If you've been working for a while and want an easy way to improve your practice, and your general impulse when working with other folks code isn't to follow down to that code from your IDE, there is a lot of worse advice than to just go ahead and look at underlying code other folks have written.

I get your point. One of my points is reading somebody else's code isn't for beginners. This looks aligned with your last sentence.

Found this recently: https://annot.io/

I learnt a lot about react codebase reading through this: https://annot.io/github.com/facebook/react

Easier to read annotated code unless the source code is well documented.

I think the quickest way to improve most code is to write it in functional style. You don't need a functional programming language you can write in functional style in pretty much any mainstream language without difficulty. Freedom from side effects makes composition and testing so much easier.

An important thing to remember about reading code is that it does not read like prose. More often than naught, reading raw code, even in the most logical sequence possible (say, UI - View - Controller - Model - Migration), will still be deeply confusing.

If you can get a local version of what you are trying to read running with easily modifiable source code (good luck), then you'll be able to execute and watch for changes. In my experience, the two most helpful ways to "read" code are using the tests first and documenting functionality second, both of which the author mentions.

I agree that reading code is extremely important for improving as a programmer, but the code has to be read analytically. That’s hard work, because it means understanding the problems and subproblems that the code is solving. For example, you may have seen the longest identical subsequence algorithm used by diff, but analyzing the implementation in V7 Unix is a different learning experience. Or if you’ve studied interpreters, you could look at the awk sources maintained by Kernighan to see how a fairly complex interpreter fits together.

One great resource I found recently is the series of books called The Architecture of Open Source Applications.


Books are available for free on the website. I'm currently making my way through volume 1, and I can say this is exactly what I was missing - a real-life study of "the bigger picture", of how the code is structured not just on the class/method level, but on the subsystem level too.

I feel like I learned sane C++ by reading LLVM code.

Yeah LLVM is great. Not everything is of the same level, but overall it's way better than average I'd say. Boost as well, but it sometimes gets ridiculously complicated (both in code and to read it) in order to be able to deal with all different ancient compilers.

I completely agree but in many cases, as opposed to a book, I don't know where to start. And in many cases you do need some domain knowledge or at least understand the requirements and mentally map code to what it's supposed to do. Reading code with its unit test I guess is the best way.

Is there a good list of "must read" code that someone is curating that you recommend?

I love reading commentary along with code, especially from the original authors. It's dated by now, but Beautiful Code[1] was a fun read. I really appreciated the chapter on the implementation of Subversion.

1: http://shop.oreilly.com/product/9780596510046.do

I've been doing literate programming for my own projects lately, and I'd really like if more programs were written in this way: creating a complete narrative for a reader to understand the problem and the solution is certainly better than trying to piece together a story from uncommented pieces of code.

This is a good suggestion. I'd also add answering questions on stackoverflow to this list. Often times you'll know the answer, but need to refresh yourself with the documentation before answering. Great way to keep skills sharp and help someone out.

I have found that reading shit code improves mine more than anything (my own included). Whenever I can't comprehend something easily, its usually time for it to be refactored. I think about how I would expect it to be if written well.

Any recommendations on good ES2015 code to read?

What's a good codebase for reading Go code?

The standard lib is one of them.

You can start with Code generator

By reading other people's code you start to get a feel for how many ways you can slice an apple. Many ways.

I find even choosing the degree of formality is often difficult. If you have a gander at Oracle/Sun's JavaFX implementation, you'll see just how much code, how much complexity goes into making a large and comprehensive API - and also who the architecture is about 4x more complicated due to their will to try to build rendering pipelines, which is ultimately an optimization of sorts.

And then of course the quick, dense, poorly commented code on some node.js implementations that seem to be novel and smart, but nevertheless threadbare.

Finally - it seems that there is quite a lot of variety in common practices particularly in Javascript.

Guidelines | FAQ | Support | API | Security | Lists | Bookmarklet | Legal | Apply to YC | Contact