On Revising in Programming and Blogging

Posted on August 16, 2016 by Richard Goulter
Tags: ,

In one of the more fascinating sidebars in “The Cucumber Book”, Dan North discusses his first experience pair-programming with Martin Fowler; initially aghast that Fowler spent time re-arranging the test code (and at times, duplicating) snippets of code.. until realising the improvement the changes brought: the test code became a more readable story.
(The principle “Don’t Repeat Yourself” was superseeded by – wait for it – Direct And Meaningful Phrases).

I mention that because it draws a connection between programming and writing.
– Two areas which at first glance share much in common (both involve textual content), then not so much in common (computationally interpreted texts by computers vs naturally interpreted texts by people; so further connections are usually interesting to make.

Anyway. I bring that up because recently I’ve had fun tinkering with old side-projects of mine. (Obligatory commitstrip). – Don’t be shocked, but such play-around side-projects tended to be in fairly unmaintainable conditions: a bad (or absent) README file; poor (or absent) documentation; poor (or absent) tests. (Let alone other things, like how easy the project is to get up and running, file organisation, etc.).

It’s kind of fun to do this tinkering, especially with the goal in mind of improving maintainability and/or how polished the project is, since there’s a feeling of bringing order where there was disorder.
– In doing so, a lot of this involves re-reading code; code that was written a long time ago. I reckon this has helped me to value the importance of documenting things, and on commenting about subtle concepts which explain why things were written the way they were. (A counter-lesson of learning between bullshit documentation and good documentation probably needs me to neglect the side-project for another half-year or so before coming back to it).
This maintenance also makes it clear that more time will be spent reading the code than is spent writing it. In the case of my side-projects, presumably I’m the only one even reading it.

But I find when I write blogposts, I usually hate re-reading what I’ve written. (The same applies for writing for schoolwork). – It’s not that I never hit the backspace key before I publish the post, though.

I know that for authors, writing a book involves not just putting words on the page, but a process of editing and re-writing.

My blog and my programming side-projects have similar standing: Neither are apparently wildly popular, but I still find value in writing them for my own sake.
– However, by parallel, just as the code in my side-projects were in an abysmal state when unmaintained, it’s hardly a stretch to say that my blogposts (and my writing ability) .. would improve with attention.

– To be honest, I do feel bad about this neglected state for a handful of my blogposts: the ones which are found high-up in Google searches for particular keywords (particularly my SBT v Gradle, and OneNote v Org-Mode posts); there’s a clear difference between what I’d expect to read for the title, and what the post contains.
For opinion-based posts, though, it’s disingenuous to silently make edits without notice. (On the other hand, if old opinions cannot be removed, that makes it possible to attack someone for an opinion they used to hold, and people can be silly enough to do that).

Newer post Older post