Letters from the Editor

There was an unusual juxtaposition a few weeks ago, a reflection worth sharing about doing design and code reviews.

My wife was interviewing for a job to be a book editor, and among her interview topics were: how do you get an author off a bad path? How do you get the poor sections back into shape? What are the conventional symbols for copy editing? Naturally as a good husband I did a little web scrounging, and I came up with some sites with the copy edit marks.

I was struck by how self-restrained the markings were.  The editor’s job is not to rewrite the book or article.

It is quite a difference to contrast this to code reviews, design reviews, meetings I’ve attended.  Many were too much like the SEI’s “don’t do this!” video on code reviews: rewriting the presenter’s words, pushing a new design in, brainstorming algorithms…

It’s quite an art to be an editor.  Since I supported the family for a few years on writing, I know how much a good editor can do for your writing.  I think we need to do the same thing reviewing each other’s technical work.  How?

• don’t bend over backwards to grok the presenter…  your next step will be to redo his work
• if something is unclear, label it so
• if you need technical detail, don’t guess it – demand it!
• if you make a comment longer than five words – scrutinize it
• your best tool for guiding a software developer or a software designer is the question – don’t lead, just take the writer along as you explore that writer’s work - or programmer’s work

I can’t imagine a programming world with reviews done in the spare style of copy editors’ marks – but I can dream!