Wednesday 22 February 2012

Copy-and-Paste Can Help Avoid Mistakes Too

In the software development world the term “copy-and-paste” is synonymous with bad practice. Web sites and books are filled with advice about how you should avoid duplication in code and maintain a Single Point of Truth (SPOT) or Don’t Repeat Yourself (DRY)[*]. One could almost be forgiven for ripping the X,C, & V keys out of the keyboard for fear of succumbing to such a sinful practice. And yet I do it all the time, way more than most of my colleagues it seems. Of course I’m not talking about duplicating code though, that would clearly be wrong...

Some months back we had a bug which caused quite a bit of head scratching as it was a subtle spelling mistake in a .cmd script (%valueData% instead of %valueDate%). Watching the developer at work intrigued me because where I would naturally have copy-and-pasted the variable name from a few lines below, he typed it out by hand. Just yesterday a colleague was surprised when they couldn’t see the files they were expecting in a folder and it turned out they had mistyped the folder path. What I found amusing was that the folder name was readily available in a text editor on the other screen (which itself was a copy of the wiki page I use for the same task) and so a quick copy-and-paste would have avoided the error.

The way I write wiki pages and release plans is very much with the copy-and-paste approach in mind. The textual description is like a comment in the code, there to advise the newbie and provide links to the supporting rationale and concepts. But what the experienced[#] developer wants is just a checklist of items, or perhaps a template that they can copy-and-paste onto the command line, into their text editor, run with their SQL tool, etc. Perhaps it’s just me, but once I step outside the woolly realm of writing English prose and into the precise world of programming I immediately look for that safety net that will help me avoid losing time due to “simple” mistakes, no matter how small. In some cases it may only save a minute or two, such as learning on the compiler, but in others it could be hours if the outcome is to bork system testing which then has a knock-on effect onto my team-mates.

Of course my way is far from perfect too and it is fraught with a different set of problems instead. Have you ever copy-and-pasted a command line from a Word document and found it doesn’t work? Did you then waste time, grumble constantly and gnash your teeth only to discover that Word had “intelligently” replaced a pair of en-dashes (--) with a single em-dash (—), or worse converted them from their ASCII to Unicode counterparts? They call it “smart formatting” but in this instance it’s anything but smart! Maybe that’s the reason why Microsoft eschews the “-“ command line switch convention in favour of “/”?

The second common mistake I run into is with copy-and-pasting from the very wiki pages that are designed to save people from making mistakes. Web browsers[+] like to be intelligent when you copy a block of text (such as an example command line) so that if you select an entire line they will “helpfully” terminate it with a newline. This has the wonderful effect of executing the command right after pasting it into a console window! No matter how slowly or carefully you select the text, the moment you reach that last character the selection box automagically expands to include the nauseating newline.

In the end mistakes are always going to happen, so choose your poison...

 

[*] Matthew Wilson even likes to combine the two and call such artefacts a “DRY SPOT” which creates a wonderful metaphor.

[#] “Newbie” and “experienced” in this context relate to their knowledge of the system, not how long they’ve been in the profession.

[+] No doubt this will incite the usual tirade of “why are you using a stupid browser like IE, get a ‘real’ browser!” comments. I’ve answered that before.

4 comments:

  1. For filesystem paths, one can also drag those to a cmd console. This seems not widely known.

    Cheers, Martin

    ReplyDelete
  2. I found the only semi-reliable way of avoiding errors like this is by explicitly taking my fingers off the keyboard and just looking at the command; and that still goes wrong sometimes.

    Separating out write and look and commit steps seems to help a lot.

    I want a keyboard with a detachable return key that I can put somewhere just out of reach.

    ReplyDelete
  3. You're not using MS-Word anymore, but plaintext with Markdown markup or similar, are you ;)

    cheers,
    Martin

    ReplyDelete
    Replies
    1. What I want to use and what my client dictates we use are really the same thing. Generally speaking you can substitute "SharePoint" for "Word" these days but the problems haven't gone away :-).

      In fact we used to have all our code and notes in a GitHub wiki done with Markdown. Then the source had to be moved to TFS and the wiki to SharePoint. Go figure...

      Delete