Sunday, 5 October 2014

Secret Scripts: the antipattern

The Secret Script is something I've been aware of for a while and, although I'm fairly sure I didn't make it up, I can't find any reference to it on Google. So I'll need to explain what I mean rather than just supplying a link.

A Secret Script is some procedure, possibly manual or automatic that you have to know about to complete a software build. It isn't intended to be secret as such, in fact it is one of those things that everyone knows, except the new guy who can't get his build to run.

You can see how these things start, especially in a small team under pressure to deliver. Cut a quick ant script to create a directory and copy some files to it, hack the maven settings file, and make sure you set up that environment variable. Sure, now everything works, and it works every time, so we can forget about it.

If you are building open source projects, where you put the entire thing up in the cloud with the expectation that anyone in the world can pull it down and build it on their machine you cannot have secret scripts. Not ever. If I pull down an open source project and it doesn't build first time that's a signal to delete it and find something else. But closed source have more leeway here, especially if the team is small and information can be easily passed around.

Note that I am not referring to documented steps. You can have a couple of dozen manual steps in your ReadMe file and, as long as that forms part of the project, ie anyone pulling down the software gets the ReadMe file in an easy-to-find directory. Those steps aren't secret, they are easily discoverable.

I said closed source projects have more leeway but not very much more. Every new hire programmer needs to get past these secret scripts. You either have someone who knows sit with them to get them going, which is time consuming, or you leave them to figure it out for themselves, which is even more time consuming, not to mention discouraging for the new guy. There is always the danger than the people who know have forgotten they had to edit some config file two years ago anyway and will be just as baffled as the new guy as to why his build fails.

And with modern tools there should be no need for this. If you're a Java shop you are probably using maven or maybe ant. On a new machine anyone ought to be able to type mvn or ant on a command line and get a working build. If they can't the system is broken with secret scripts.

Secret scripts have a sort of mirror pattern which is, unfortunately, still an antipattern. I call these decoy scripts. A decoy script is a script or procedure that is right there in plain sight looking like it is important and useful, but which does not actually work and everyone but the new guy knows to ignore it. The new guy tries it out, finds it doesn't work, and tries to fix what is obviously a local problem. The certainty that everyone else has this script working will lead him to waste hours trying to fix what has to be a problem local to his machine.

Here are some examples of decoy scripts:
  • Out of date instructions in the ReadMe file.
  • Unit tests that don't pass (and aren't flagged as @Ignore)
  • old ant scripts that refer to invalid paths
These things are fairly easily avoided, and fixing them can save a lot of time.

Saturday, 4 October 2014

My trousers caught fire!

There's the proof. Trousers and socks ablaze. Fortunately I was wearing other trousers at the time.

This time of year we burn the piles of prunings and other tree trimmings we've accumulated since the start of winter (it is spring here in NZ). We'd started it with some paper in a cardboard box which I took to the back door afterwards to fetch some tools.

When the blaze was starting to die down we headed back and found the box was just ashes and my gardening trousers that lay beside them were alight. Obviously the box had been too near that fire. Easily fixed and no damage done, except to a very old pair of trousers.

Could have been worse though.

Wednesday, 1 October 2014

Domestic Dramas

We got back from hols and, as you do, turned on the espresso machine. Bang!
What? Turned it off then back on. Nothing. But not on either. Checked the fuse box. Yep, one of the cutouts has flipped. I took the back off the espresso machine and wiggled some wires, one of which looked a bit blackened. Ficked the cutout back on and tried again. Bang! There were visible sparks this time. Okay, that's not good.

I disconnected the espresso machine altogether, called a service shop and arranged to take it in there to get fixed. It's a wonderful machine, one of those Electras with a brass eagle on the top, and it does a good job, been doing it for nearly 20 years now.

Meanwhile I fetched the emergency backup espresso machine (yes, we do have an emergency espresso machine cos of a more minor problem 3 years ago) and set it up on the kitchen bench. Espressos followed.

Getting the main machine to the repair shop is a little tricky because it has a plumbed in water supply. I remember when we set this up and there's a shut off on the incoming pipe so the machine can be disconnected without getting water everywhere. It is hidden behind a panel in the bench below. I took off the panel, found the shut off and turned it off. Then I set to disconnecting the machine.
The moment I got the water supply line off the machine I got water sprayed in my face and pretty much everywhere. What? I shut off the water! I did! (this, among other things was what I was yelling to Mrs as I asked her to go shut off the mains).

That's complicated too. We gather water from our roof and store it in a tank, then a pump sends it to the house. The pump is smart, it detects the drop in pressure when we turn on a tap and cranks up to maintain it. So Mrs ran outside to the pump switch while I jammed my finger across the tube to stop it squirting. It seemed to take a long time.

Next step was to find out what was going on with the shut off that didn't. I got a wrench and took it off... and noticed water was still dribbling steadily from the pipe. Huh? We turned off the pump. The kitchen tap is still on and is not running, that proves it.

Except that this particular pipe end is lower than all the taps because it under the bench. That means it is below the top of the water tank, so there's some pressure even without the pump running. I need to turn off the tap on the tank. Leaving Mrs in charge of a bucket to catch the dribble I went out and struggled with the tap which hasn't been turned in at least 5 years and didn't feel inclined to now until I started hitting it. That sorted out the dribble. So we were no longer in danger of flooding the kitchen any more than it was already.
I had enough bits and pieces to contrive a bung in the pipe and then I could turn the water on again. It held okay. Whew.

That's enough excitement for now, but I am going to take a long hard look at that shut off that didn't before I put this back together.