One Way to Improve Your Coding
changelog.com
changelog.com
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.
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.
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. :)
One of my favorites is Rob Landley's Aboriginal Linux:
http://landley.net/aboriginal/about.html
I highly recommend his blogs if you're interested.
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.
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.
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...
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.
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.
Still, fun to think about. If you know of any studies, I'm interested.
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.
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.)
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.
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.
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
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
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?
That being said, I'm not a fan of grey on white either.
Agree in general though, more & more I end up tweaking site's font-size/line-height/contrast to bring it back to normality.
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.
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.
It seems like it might be worth taking advantage of OLEDs ability to do unlit black.
It is, but (very) dark gray text on a (very) dark gray background is fine. This light gray on white thing is just nonsense.
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.
I get design is important, but it should NEVER be at the cost of removing usability.
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.
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.
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.
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.
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.
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.
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".
The key is seeing others code warts (or lack of them) makes you identify your own warts.
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".
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.
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.
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.
http://grepcode.com/file/repository.grepcode.com/java/root/j...
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:
https://sourcegraph.com/github.com/gorilla/websocket/-/blob/...
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.
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.
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.)
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.
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.
> 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.
> 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.
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/
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
https://www.amazon.com/Computers-Typesetting-B-TeX-Program/d...
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.
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
Still feels like stealing, but that's my problem :)
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.
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.
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.
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 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.
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.
http://aosabook.org/en/index.html
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.
Is there a good list of "must read" code that someone is curating that you recommend?
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.