A lot of the past year I spent in a highly concentrated study of programming. I've been learning both the semantics of programming languages and the high-level art/philosophy of coding.
And there's a lot of advice flying around. It doesn't take you long to discover that programming is a field whose inhabitants are keen to look at it not just as a job, but as a highly important zen/philosophical/artistic way of life. They care a lot about how you code. Comment your code, don't overcomment your code, use top-down design, use bottom-up design, code for readability, code for efficiency, use descriptive variable names, refactor often, modularize everything, and don't break out of a loop early unless you turn around three times and spit first.
I'd certainly like to follow all of it. I'm trying to synthesize it all into some idea of the right way to do it. But something I notice is that there are terribly few examples to go by. I find it odd that the experience of learning programming, be it from a school, a book, or a website, is not full of examples of other people's real-world programs.
I've realized that learning to write well-written code is very similar to learning to write well-written English. It's hard to declare rigid rules that you can just follow to get there. There's plenty of advice, but advice in a vacuum isn't extremely useful. You need positive examples of good writing. A lot of what makes effective writing is that it's easy to follow for people used to it being laid out in a certain way. It also uses constructions that are efficient and effective. That's for both written English and written programs.
You learn to write English well by reading books and essays written by the masters. But you're supposed to learn to write code well by.. writing code. I find it strange that there aren't far more examples of well-written programs in books and university classes. There are whole books and websites of collections of essays and stories! Why not programs? There are certainly enough people who care about it, let me tell you.
This post was prompted by reading an essay by Steve Yegge on overly-commented code by novice programmers. I'd always heard people putting an emphasis on well-commented code, so it was interesting to hear the arguments for why it can get cumbersome. I thought it was compelling, and I'd like to put the advice to use in my coding. I want to learn, Steve Yegge! Really! So please, just show me how it should be done! I want to be an E.B. White or Christopher Hitchens, but I can't do it without examples!