Case Statement

Lunch and Learn: Articulate Coding

We get lunch brought in to work on Fridays. I took the opportunity to show great videos to the team while we all ate. It’s a lunch and learn with zero effort.

Today we watched Kent Beck’s QCon talk on Responsive Design. It’s certainly worth checking out if you’re bored, although it is a bit slow in parts and the non-mic’d audience questions do get annoying.

There were two really great ideas in the talk that will probably keep me from sleeping tonight. The first was the concept of design principles. Beck says that a design principle is what you fall back to when patterns fail you. Principles help cull the decision space and narrow your design to something that is less likely to bite you in the ass down the road. He suspects there are a number of universal principles like “don’t repeat yourself” but also personal principles like “make safe changes” and business principles like “our software exists to assist people to make decisions”. The subject of Design Principles is easily the topic for another post.

The second idea that really struck with me is the anecdote near the beginning of the talk. Beck talks about wanting to deconstruct his own design philosophy, wondering if it was possible to actually break down every decision he makes when writing a program into a set of personal design patterns or strategies. So he set out an experiment.

Beck’s experiment is simple.

He would type a few characters and then stop. He would think about those characters and determine what pattern they were expressing. Then he thought about why he chose that particular pattern. Next, he wrote down his findings and typed a few more characters. He would only continue if he had documented the new pattern or if he had already encountered the pattern previously.

If you think about this, it’s a pretty crazy experiment. When we program, we face multiple decisions on every line. For instance, imagine this method declaration in a typical oo language

public function doSomething($id, $job, $newname = 'Anonymous') {

Why did I explicitly set the scope to public?
Why did I name the function like this?
Why did I use camel case for the function name?
Why didn’t I define types for the parameters?
Why did I put the parameters in this order?
Why did I choose these parameter names?
Why didn’t I use camel case for the last parameter?
Why did I put the open brace on the same line?
Why did I use single quotes instead of double?
Why did I indent?
Why did I use spaces instead of tabs for indent?
Why did I use four spaces for the indent?

Here are twelve minor decisions[*] for a line containing only seven words, more significant design principles like dependency inversion or single responsibility haven’t even been touched. You quickly realize that the number of instincts and habits that we all have as coders must be enormous. We arrive at these patterns deliberately, through convention, and by accident. For example, I deliberately put the $id parameter first because I know I’m building an api that uses that same parameter everywhere and it will maintain consistency for those calls. I use camel case and leave off the typedefs because that’s the convention in the team’s code base. And when I look through the rest of my code I find that my use of single quotes and double quotes is completely random, I suspect that my tendency to switch languages often has made it difficult to build up a consistent pattern in my mind.

Now, Beck continued to document these decisions as he built his application. He found that the same decisions began to crop up more and more so that by the end he was able to code without documenting anything new. At the end of the project he found that his personal design patterns were now mostly written down. More importantly, he found that he was better able to speak about, defend, and consciously review those decisions.

He became more articulate about his craft.

Remember, this is a leader in our field with decades of practical experience who’s written many easily digestible books and papers about deeply complex problems. Despite all of that, he still found that this exercise helped him communicate on a whole new level.

This really resonated with me because I feel that I am not always as articulate as I should be. I find it very easy to wave my hands and say this code smells, that’s a good idea, or I’d rather do it this way without really understanding why I say it. The best developers that I’ve worked with always find a way to explain not only why their design decision will work in a particular case but why at a fundamental level it will be more robust, maintainable, and readable. I sometimes find that magic thread of reasoning and am able to thread the argument with the correct words to explain myself exactly. But those moments are fleeting. Hopefully, through deliberate practice I will be able to improve my signal to noise ratio, stop the hand waving, and articulate my positions with more reasoned arguments.

Personally, I can’t wait to try this experiment. Maybe not for an entire project, but a new class file could provide me with some good material for introspection.

As I kick off this blog, with many of the same goals as I hope to gain from the experiment, I must remember there are no silver bullets. If I want to be able to speak about my craft more eloquently I have to speak about my craft more often. Although I may think about development every day, I hope that putting my thoughts down in writing will help me to articulate my code.

Follow the discussion on Hacker News

[*] I can think of at least four more decisions I made when I wrote that line, how many more can you point out?