Editing

When I was a student, back in the day, I had an Elite portable typewriter which had belonged to my grandfather. (The fact that it was Elite meant I got an extra couple of lines of words per page: N-page essay requirements always assumed Pica, which had fewer lines per page.)

My practice throughout my university days was, invariably, to write out every paper in longhand, edit the draft heavily, and then transfer the edited draft to the typewritten form for handing in, doing a second edit as I went.

A period in publishing as an editor taught me the standard markup formats, which I had not bothered with up until that point. But by that time computers were coming in and editing tended to become a continuous process onscreen; I rarely had the opportunity to use paper editing on my own texts.

(I may add, in passing, and as qualification in what follows, that I still think that printing out and editing a text is the only really effective way to end up with a good text. I have occasionally edited source code in this way. It is the best way, bar none, to attain to brevity.)

These days all my work is onscreen; i don't even have a printer. I do, however, find that the discipline of separating writing and editing remains critical.

I will regularly make a first draft of a class, sleep on it, and decide, on sleeping on it, that the design needs significant changing. This is too close to the original composition to be refactoring; it is, fundamentally, part of the original design process, with no re- about it.

Much of the time this leads to simplification; when it does not, it is because it leads to generalization, more complex in one place, less complex overall.

(I might as well throw in a note about "emergent design". I tend to agree with James Coplien that design is something which has to happen as its own discipline, and can't just emerge from work with concrete classes plus some general patterns principles. When I work on a feature, or on a bug once it has been analyzed, I never work without hewing to an explicit design, even when that design is not written down. But from that perspective design is not so much part of composition but its prerequisite: I couldn't have done that longhand writing without a good sense of what my overall structure was to begin with.)

A lot of the code that I see in production looks as though it was produced by developers who left off as soon as they got the first draft that actually worked. It's verbose and full of copy-and-paste antipatterns. Boolean flags are used instead of strategies and in some extreme cases independent access to global variables is used instead of parameter passing.

It uses idioms which were learned early but are not optimal. For example, most developers started out writing loops using for and while; but in C++ maintainability, clarity, concision, and speed of execution are better served by using the STL algorithms. One might draft out one's thoughts using a for loop, but finished code should have the additional thought put into it of using an appropriate algorithm.

In all cases these are less clear and less maintainable and in most cases also less efficient at runtime. But it's a first cut that's left in that state because it works and people won't edit.