Link Twitter Facebook LinkedIn Github Email

At Dinner

At a tiny Japanese comfort food restaurant, J. and I are the last couple left, both stuffed, leaning back, can't-eat-another-bite. A tiny, friendly Japanese woman—the chef, I think—appears at our table to refill our water and tea.

"How is everything?"

J. is startled, glances at the chef and then back down at her half-eaten meal.

"Really good!" I say.

J. immediately takes another bite of her chicken, swallowing with a pained expression. The chef chuckles and says, "Good, good!"

J. keeps eating. The chef beams for half a second, satisfied, then walks away.

J. sees me watching her eat regretfully and turns bright red, afraid to glance over her shoulder to see if she can stop. I grin from ear to ear—but I give her no hints.

Writing code and prose

One of the most important qualities for effective programming in large codebases is good writing ability—not writing code, but writing prose for other humans.

Undoubtedly, this is not a surprise to long-time industry veterans (after all, we don't often program in machine code anymore), but it's a quality I often find is overlooked by engineers that arrive straight out of college. Those that I see write the cleanest, most maintainable code are those who write prose well, whether in documentation, in emails, or in their everyday lives.

Many aphorisms about writing style translate fairly well to coding. Consider the following selection of principles from The Elements of Style by Strunk and White:

  • "Place yourself in the background," and "Do not overwrite." The best code does its job honestly and without obscuring its meaning with the author's "style." If code is so obviously stylized, it is probably written poorly. Exploiting all of the obscure bells and whistles of a language makes for brittle, obscure code.

  • "Work from a suitable design." Plan ahead and make deliberate design choices. Choosing the right architecture makes a huge difference in how cleanly or how tortured your code will read.

  • "Revise and rewrite." Or in the words of Fred Brooks in The Mythical Man-Month: "Plan to throw one away." Your first solution will take longer than expected, have problems you didn't foresee, will likely have code put in the wrong places, and have abstractions drawn at the wrong lines. Write a second draft.

  • "Use definite, specific, concrete language." Vague names like lookup_table or callback are useless in much application code. Use more specific, concrete, and informative synonyms like users_by_id or on_success.

  • "Omit needless words." We need not be obscurely terse—we aren't counting characters for source code anymore—but concise, simple code is best. Use abstractions and language features to remove boilerplate and focus on core logic.

  • "Express coordinate ideas in similar form." Similarity in structure emphasizes similarity in idea, allowing readers to pattern match and understand your code more quickly. Beware, however, the limits to foolish consistency. 1

  • "Keep related words together." Save your reader from having to jump around different files and switch contexts to follow lines of logic. It is tiring and difficult to do, even with the help of an IDE. Use tools like promises, monads, and other abstractions to write code in linear, readable progressions that would otherwise be fragmented.

  • "Prefer the standard to the offbeat." Be idiomatic. Follow the standard styles of a codebase and language community. Don't vary for the sake of variance.

And one more aphorism from journalism that I think applies to programming:

  • Don't bury the lede. Document up front. Put public methods and interfaces at the top of a file, not halfway down past implementation details (when possible). Your code should read like a newspaper article: headline to start, the main gist at the beginning, and then more gristly details further down if the reader is hooked and interested.

Still not convinced? See how much of The Swift API Design Guidelines reads like advice for writing prose.

  1. "A foolish consistency is the hobgoblin of little minds" -- Emerson, Self Reliance (1841)

2013 in review

This blog has been pretty quiet since April, but that's because there's been an amazing amount of stuff happening. So to sum up the year since then:

  • May 4: Attended my brother's college graduation from the University of Michigan.

  • May 7: Celebrated 2-year anniversary of marrying my wonderful wife.

  • May 10: Defended my thesis. (And passed!)

  • May 11: Started a cross-country drive with my wife to San Francisco.

  • May 11-18: Saw Akron, OH (Swensons!!), experienced Wisconsin squeaky cheese curds, saw the sun rise and set in the Badlands, walked the lava flats and climbed a cinder cone at Craters of the Moon (thanks to the wonderful suggestion of my former high school physics teacher), saw beautiful, amazing sights at Yellowstone, including my first bison calf and Artist's Point (seriously, not to be missed).

  • May 18: Arrived in San Francisco, moved into a temporary place.

  • May 21: Started work at Dropbox, Inc. as a software engineer.

  • May 26: Attended the wedding of two of my closest friends.

  • June 11: Moved into a permanent apartment in the Castro.

  • July 9: Attended my first professional conference, but as one of the people helping out rather than as an attendee.

  • September ??: My graduate school's board of trustees met and approved degrees granted over the summer, including mine. (Whoohoo! Now I'm actually a Doctor.) I got my diploma in the mail, but they asked for it back, saying they misspelled my name (they forgot to include my middle name). Maybe it's a trick...

  • September 22-27: Took a trip to Boston to help Dropbox with on-campus recruiting.

  • October 7: 10 year anniversary of starting to date above-mentioned-wife.

  • November 22: Wielded a hammer and anvil for the first time at the Crucible in the East Bay.

  • December 31: Realized it's New Year's Eve and scrambled to write this post.

It's kind of strange now to be on the West Coast after a lifetime in the East, especially in combination with no longer being a student (after 22 years of schooling!–enough is enough). Life is simultaneously more sedate in California and more exciting for being out of school, especially now that I'm working at a fast-changing tech company. I'm pretty fortunate to be extremely happy with where I am at the end of this year, professionally and personally, and I'm quite looking forward to the next year and what it'll bring.