Wednesday 22 February 2012

OK & Apply - A Failed UI Experiment?

As you may have guessed from my previous two posts, I have been paying far more attention than usual to how other IT professionals[*] work. The most recent one that caught my eye and has no doubt been done to death in UI circles is the OK and Apply buttons on dialogs. It’s funny to watch people first push the Apply button and then the OK one. The question is whether they don’t realise that pressing OK has addition affect of applying the changes, or that they don’t trust that just pressing OK is enough? I’m sure it’s the latter - a belt and braces approach.

I know how they are supposed to operate, but I suspect that’s only because I was doing a lot of UI work when Windows 95[#] appeared and so I was paid to know all the UX guidelines. Perhaps it’s time to take a trip down memory lane and visit the “Interface Hall of Shame” along with a quick Google search to find out if/when this UI faux pas was officially deprecated...

 

[*] I’m always looking to learn new tricks and techniques to be more effective and other IT professionals is obviously as good a place as any to look as this is (supposedly) their bread-and-butter.

[#] and Windows NT 3.5 with the shell upgraded to 4.0.

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.

Tuesday 21 February 2012

Don’t Let Your Tools Pwn You

Modern development tools such as IDEs and their associated multitude of plug-ins, such as ReSharper, can definitely improve productivity. But they can also reduce it too if welded without due care. In some cases it may not be yourself that suffers the loss in productivity but your team-mates because you were unaware of what that tool actually did.

The original impetus for this post was actually watching someone dig themselves into a right mess with ReSharper. I suspect they had got so used to accepting every pop-up that ReSharper threw at them that they didn’t notice when ReSharper had suggested the wrong change. The code didn’t compile now but it wasn’t obvious why as the wrong turn was some minutes ago and they were focused on the code they were writing now. After all, the previous code did compile so why could the mistake be back there?

Being “old school” I used the compiler output to point the finger rather than ReSharper’s advice and traced it back to the source. The earlier mistake was to mistype the inheritance of a class and then let ReSharper implement it automatically. This mistake initially swapped compile time errors for runtime errors (throw NotImplementedException is the default implementation) and unless you use a test-first approach the feedback loop between making and discovering the mistake grows rapidly.

The more recent impetus is another tale, once again involving ReSharper, that caused another person pain - me. As part of a large refactoring exercise one of my team mates had to split some core classes off into a common assembly for use by the new client application. They chose to use ReSharper for the job which makes perfect sense as refactoring is one of its main features. Sadly they didn’t know what ReSharper was also going to do at the same time...

These changes all happened in the background on the trunk and it wasn’t until I came to merge some last minute changes from our release branch that things started to get dicey. I was getting a lot of merge conflicts on the changes even though I knew that no one would have touched the code[*]. Well, I knew that the namespace at the top of the file would have changed as a consequence of the other person’s changes, but definitely no more. After looking through the Subversion log I could see that some whitespace has also changed and my gut reaction was that someone had also “fixed the formatting” at the same time as making another change. I didn’t spot this myself at first because the diff tool I originally used had “ignore whitespace changes” still set to ON after an earlier unrelated comparison! Unfortunately the piecemeal way the refactoring had been done also meant there was more noise in the SVN log[+] than a single commit.

Ultimately it took me an hour and half to convince myself that the merge was sound when it should have been trivial. I didn’t notice at the time but the unexpected whitespace changes had also destroyed the careful formatting of a table that needed to be kept in sync with a similar block in some SQL code[#]. This cost me another 30 mins or so to sort out. In retrospect I would have been better off reverting all his check-ins first, fixing the build and then merging mine in after. But that’s part of the problem with finding unexpected changes - you then go looking for the proverbial needle in the haystack that you’re convinced must exist.

My natural reaction to this second issue is that the original refactoring changes should have been diff’ed before check-in (as any change should) and then the problem would have been spotted and corrected at its source. The argument against doing that would no doubt be that they don’t have the time to diff 100 or so files and anyway the change was “automatic”. The question now is whether it would have taken that person more than 2 hours (the disruption caused to me, let alone others) to diff those files and spot that the tool was doing something unexpected? I sincerely doubt it, even doing it manually. And you could probably automate it to produce a unified diff that would clearly have shown up lots of unintended changes.

OK, so that’s only two issues, hardly enough to suggest we give up our modern tools and return to the stone age. And I’m not suggesting that. What I am suggesting is that you’re careful not to get drawn into relying on the tools so much that you cannot remember how do things “long hand”. Although I mainly use Visual Studio with ReSharper for day-to-day C# development I still like to use tools even as primitive as Notepad because they are fast, will spot issues other tools hide[$] and most importantly are even available on production hardware.

 

[*] It was the kind of legacy code you really don’t want to touch unless you absolutely have to. And if you do you want tests. But you can’t.

[+] Given the limitations of Subversion is was probably the right way to have done it as its Copy+Delete approach to moving and renaming files can get you into hot water, especially when mixed with branching.

[#] Yes, in an ideal world these two bodies of code would be generated from a single source, but life is never that easy in reality.

[$] The best way to spot a file that has a mixture of tabs and spaces is to open it in Notepad. Has anyone ever chosen 8 spaces-per-tab out of choice?