The editing pass
Tuesday 9 October 2007 - Filed under programming
Anything worth writing is worth re-writing. This applies to code as well as prose.
I give paper sections and important emails a while to sit after I write them, and they always benefit from another look with fresh eyes. I think that doing this with code is worth thinking about.
Once you get a piece of code to the point where you believe it works – it’s passing its tests – go back over it and edit it. That is, go back and edit it for clarity, flow, and style. Just as if it were an essay.
This is particularly important for tests. If a test fails, it should tell a clear story that explains exactly what failed, and what it was expecting.
Things to consider editing out are vague variable or function names, and non-idiomatic shortcuts. Control flow can get tangled when working out a solution. Make it obvious. One-liners often don’t tell the full story. When you come back to a piece of code, you know the chase. It’s the first loose thread of a bug, a failed test, or an occurrence of a symbol you need to refactor. What you need is the story around it, and solid code will fill that in.
You can learn this by sharing your code or by waiting a while and reading it over again. It’s easier said than done – I don’t always do it, but I do know: an editing pass can do you good.
Something to think about: would a professional code editor help or hurt in the long run?
2007-10-09 » mike
9 October 2007 @ 11:49 am
Hi Mike,
Great advice – especially since even if you think your code is pretty efficient, once you start really editing it you’re going to find something that made sense in the first pass but which could be made better in the second.
Then, edit again.
Cheers!
9 October 2007 @ 6:33 pm
Two things along this line that I would like to try if I were working in a large team on a large project (eg Photoshop) would be:
Someone reviewing code, especially changed code. This could either be very active, editing as you describe, or more passive checking the code for subtle bugs or feeding back suggestions for refinements.
Dual programming where two programmers worked together, with one writing code and the other watching, reviewing, recommending, planning.
I have fond memories of a dual programming case from back in university where I and a friend spent all night writing a large piece of code, and after programming for many hours, it compiled and ran first time.
9 October 2007 @ 8:45 pm
I totally agree with the idea that it is good to go over code and edit for clarity, but I think it’s essential to remind everyone TO CODE WELL THE FIRST TIME. Only editing once everything is done reflects a ‘programming class’ mentality, and is ignorant of the fact that writing well documented code is enormously benificial to the coding process itself.
9 October 2007 @ 9:27 pm
Peter: I too have fond memories of huddling over a single terminal and churning out solid code, hashing out ideas in shorthand because we were both so deep into the problem.
Simon: I would hope I don’t have to remind people that they should be writing good code. Maybe I should have been clearer that I was thinking in terms of an editing pass on a function or a unit test – not a big cleanup of a whole haphazardly written module.
9 October 2007 @ 9:59 pm
[...] code Michael McCracken: “Once you get a piece of code to the point where you believe it works – it’s passing [...]
10 October 2007 @ 1:18 am
[...] Läs mer här [...]
10 October 2007 @ 4:31 am
Where I work, nothing can be checked in without a code review. The repository is even configured to prevent commits without a code reviewer’s name in the commit comment.
10 October 2007 @ 8:05 am
I’ve long though that the term ‘Software Engineering’ is a misnomer. It’s really ‘Writing Software’, code is in the end written for other humans to read, the compiler doesn’t care what you name your symbols and the processor really doesn’t care what your code looks like. Since software is written to be read, the traditional drafting, editing, review and publication model makes much more sense and is much closer to the actual practice than any traditional engineering discipline.
10 October 2007 @ 9:21 am
Don Knuth said something similar in his book Literate Programming.
10 October 2007 @ 4:21 pm
[...] michael-mccracken.net » The editing pass “Anything worth writing is worth re-writing. This applies to code as well as prose.” (tags: code programming editing style refactoring) [...]
10 October 2007 @ 5:33 pm
I just read this and it seems to describe refactoring almost exactly. I don’t know why I hadn’t thought of it before. Excellent.
10 October 2007 @ 6:59 pm
[...] this explanation of refactoring by Michael O [...]
11 October 2007 @ 8:16 pm
The Editing Pass…
Edit code just as if it were an essay says Michael McCraken….
5 December 2007 @ 12:58 am
[...] Michael McCracken: “Once you get a piece of code to the point where you believe it works – it’s passing its tests – go back over it and edit it. That is, go back and edit it for clarity, flow, and style. Just as if it were an essay.“ [...]