Oh sweet irony, redux
Paul Graham's quickie essay on how to write well ends in a single-sentence paragraph so long that simply reading it makes me feel dizzy. Want to write well? Give your readers room to breathe!
I'm more than guilty of this myself, of course. I overuse colons, semicolons, and dashes, overloading my prose with unnecessary run-on sentences. But I'm fighting back: one of my standard editing steps is to work through the text challenging every linking piece of punctuation. For me, the rule is simple. If it could be a full stop, it probably should be a full stop.
I love his ending, though:
Writing code has a lot in common with writing prose: good code is crafted to clearly express its meaning to readers. The Literate Programming methodology takes this to extremes. But there are plenty of little things that help make code tell its story. Name things thoughtfully; use simple constructs; group related things together.
And at a very basic level: your code comments speak for you. Make sure they speak clearly and well. A lot of my first impressions of reading code come from the comments. If they're misspelled, ungrammatical, incomplete, or cryptic: what does this say to me about your code?
I'm more than guilty of this myself, of course. I overuse colons, semicolons, and dashes, overloading my prose with unnecessary run-on sentences. But I'm fighting back: one of my standard editing steps is to work through the text challenging every linking piece of punctuation. For me, the rule is simple. If it could be a full stop, it probably should be a full stop.
I love his ending, though:
[L]earn to recognize the approach of an ending, and when one appears, grab it.And he's right: writing well is important. It's particularly important for techies. The best idea in the world won't fly unless you can communicate it well.
Writing code has a lot in common with writing prose: good code is crafted to clearly express its meaning to readers. The Literate Programming methodology takes this to extremes. But there are plenty of little things that help make code tell its story. Name things thoughtfully; use simple constructs; group related things together.
And at a very basic level: your code comments speak for you. Make sure they speak clearly and well. A lot of my first impressions of reading code come from the comments. If they're misspelled, ungrammatical, incomplete, or cryptic: what does this say to me about your code?
