Edit: The average piece of code is written once and read hundreds to thousands of times by people. It's not unreasonable to think of code as a read-oriented activity, not a write-oriented activity.
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?
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.
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.
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.
That's an easy one for me - get to read a lot of crappy code, unfortunately...
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.
Working through a few of these would really feel like apprenticing with a pro.
Maybe it could just merely point to real-world examples, without so much detail. I dunno.
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.
¹: INCOMING: https://news.ycombinator.com/item?id=9899766 https://news.ycombinator.com/item?id=13854431 https://news.ycombinator.com/item?id=9896369 https://news.ycombinator.com/item?id=14462125 https://news.ycombinator.com/item?id=8573291 https://news.ycombinator.com/item?id=327710 https://news.ycombinator.com/item?id=1770662 https://news.ycombinator.com/item?id=12381609
If I read code without a concrete goal, I find that I gloss over important details and fail to really grok the purpose and design of the code, and therefore do not learn all that much. However, if I'm actively debugging some code, or if I need to understand the consequences of calling some function in a library, then I feel like I get a much firmer grasp on the code, and consequently I properly absorb the techniques used in it.
So I guess I'd rephrase the advice as: Read and understand all the code you're working with. Build as many systems as you can to expose yourself to more coding techniques. Don't take any tool or library you call into for granted- be diligent and read / understand your dependencies carefully. When something unexpected goes wrong, initially suspect everything in your stack until debug data tells you otherwise.
I've seen this truism before but I never seen any actual data on this. Do you have any sources for this? My intuition says most code is Enterprise/small business code that is written once and read less than 10 times.
Write lots of code, you get better at writing code.
Programming involves both, so I think they're both needed, and you're right to call out that practicing to read code is not as often done.
One thing I'll add is make sure to tackle progressively harder problems, both in reading and writing of code.
Another one is to cover the spectrum. Go for hard in the small problems, like hard algorithms, tight inner loops, etc to large systems of interconnected components.
And make sure you learn concepts like fundamental paradigms and styles. This should also be done in the small up to the large.
I'm actually thinking of building a tool that would automate this a little - maybe it would find some code from a well-loved OSS library and get you to mark it up in the browser. Once you're done, you could see other people's comments on it.
Like most learning, you have to apply the concepts for them to stick well so just reading isn't helpful until you've practiced the ideas yourself to cement them in your mind.