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.