This is a suggestion I see given a lot, but something that falls flat to me personally. The analogy I would put forth is that it feels like reading lots of different furniture assembly instructions in the the hopes of getting better at assembling IKEA furniture. Such a thing is informative, but probably not nearly as much as just assembling lots of IKEA furniture. To those who make it a point to read lots of code, are there approaches you take or methodologies you use? Or certain things you look for? Or concepts you compare to them to in your native language?
More like encouraging the creators of IKEA furniture assembly instructions to read lots of other instructions so that they can get better at writing instructions.
An analogy for improving one's ability to assemble IKEA furniture, using this pattern, would be to watch others assemble all types of furniture in order to improve your own abilities. Wouldn't it?
I think the idea here is to look at the code for the libraries you're using. The documentation might lead you to believe it behaves in a certain way, but the actual code is the true source of truth. Open it up and have a look instead of wondering.
Something I liked about working at Google is that I never had to wonder what the lifecycle of a certain request looked like. I could always open up the code for the server I was trying to talk to, and piece together what "internal error" really meant, or what "optional" fields were actually required to make the request succeed.
That's excellent point. When I digged into express source I understood several things like how it extends the response object via prototype to add methods like send etc. Also you will understand how exactly next function is implemented and then you can literally understand anything about the library.
A great viewpoint, but not what I think the objective was. Code needs to inform humans first, inform computers second. Because of the human cant understand the code, they can't change it, and being able to change code is what decones maintainable and "good".
To figure out how to write code that informs humans well, you have to read code. See what works and what doesn't for someone who is not the original author.
Being usable without changes (what you describe) is nice, but not what most people mean when calling code "clean" or "maintainable", or even "good" (that might imply a good API, but not the code itself.
When I used to read a lot of code for its one sake, maybe the majority was in books and papers (like SICP, Norvig, Knuth, Kernighan & Whoever, "Functional Pearls", ...) which explained points the author thought especially important. There's lots more great code to read without the extra commentary (especially nowadays) but you do have to work harder to find the lessons.
To me it was especially valuable to always be asking "how might I write this better (in some sense)?" whether it's great code or not. When it's especially good you'll still think of plausible improvements, and maybe the lesson is in figuring out how they're not actually such an improvement as you think.
I think this is a good point. I have mostly gained knowledge of software design by doing this, because once I work through a process that might happen in the code, I can infer the reasoning behind design decisions.
I am still learning myself, but so far, reading production code now seems much more valuable than the pseudo code often found in blog posts. They each serve different purposes but I have found myself reading too far into pseudo code when trying to understand a concept can add unnecessary confusion. With production code, what you see is what works.
And that just gave me an idea: programming books that only use production code! It might do less handholding and would certainly be harder to write, but maybe the value would make it worthwhile.
I thought of this, too, but what I decided I wanted was a book that wrote the simplest working version of some useful thing (basic HTTP server, JPEG codec, basic CRUD web app, etc.), explained it clearly, then gradually "hardened" it, version by version, into true (actually in use) production code. Each new version would introduce an issue, possible ways of dealing with it (each with pros and cons), a well-explained choice, the code that implements that choice, and a discussion of the implementation. Then on to the next issue and another upgraded version of the code until arriving at the actual, thoroughly real-world-tested code in use in some popular system.
Working through a few of these would really feel like apprenticing with a pro.
The GP's suggestion of revisiting code reads to me a bit like the mental equivalent of opening a file to read one line, closing it, opening it and fseek()ing, ad infinitum. Works - and I totally get the GP's approach of repeated "passes" distinguishing increasing levels of significance - but in I've learned the hard way that the overall context switching overhead of this particular approach is so immense that my eyes would glaze over long before I took away anything useful. The real answer there is to inhale the overall structure and reach conclusions about what to prioritize. This most definitely requires a good working attention span, something I've only had access to more recently.
As for your idea, what about: pick a project you think highly of, or find a bunch of code you've read good reviews of¹, and write a reference work on it over a period of time. Maybe publish for free, maybe don't.
I suspect (having never done this idea, and only thought about it for a short time) that the initial tendency could be to simply explain what's going on in the code, in the same sense of "but these comments explain what the [well-written] code's already clearly describing".
What would be even better would be to make the reference serve an introductory context, and allow newcomers wanting to understand the code to use the reference as a fast-track guide. (Oh! I actually have a (maximum-difficulty :D) example of what I mean! 1st two paragraphs: https://bugs.chromium.org/p/chromium/issues/detail?id=671498...)
This would obviously be quite a challenge, not just because of the comprehension/study required but because the goal would then be to "get out of the way", as it were, minimizing/eliminating editorialism etc and just providing enough structural "fluff" for people to stay engaged and maintain flow/focus on the topic (which is very tricky for me to do...).
This could actually be a very interesting pastime to consider. Thanks very much for writing your thoughts.
Agreed. There's certainly value in reading foreign code, but IMHO the value is much greater if you spend a bit of time trying to implement it yourself, and only then see how they implemented it and consider what you could learn from their approach.
