Wednesday, October 2, 2013

When a Script Becomes an Application (Sub: "What? It has to do that too?/You're still using that?/Comeon guys, it's not that many lines!")

I've posted a couple times recently about a migration project between one wiki to another and work I've done to create a script to move the content. I'm going to give a spoiler here: Whenever you offer to automate a part of a project and prove you
can do it, more things will get shoved into the "automate this, please" bucket.

As long as the task makes sense to automate, this is not a bad thing. It really just means that your non-programmer coworkers are starting to understand the power of programming.
"Unlimited power...of programming!"
But at some point, your simple script to automate documents moving becomes a mass of sphagetti code. It's no longer a script, it's a monster. And suddenly you realize you should have asked for the time to design, build, and create tests for the thing properly. Usually by this point, you're too deep in to go back and start over. At least I am.

The script works (really well, I might add). But if someone asks for another feature or someone wants to modify it for use in another project, we're going to have a problem. I'd like to share how I got here, and give you a few key things to watch out for to know if you're script is becoming a monster.

At the start of the project, a simple task was described (download HTML documents and save them on a file share). Easy enough to automate.

Then, the task expanded to, "Also push them into the new wiki." Also, not a big deal. Still pretty simple here. No red flags.

RED FLAG HERE: Because the project was in full swing when I pushed for automating the migration, there were already interns copying and pasting documents by hand. They hit a few issues with the copy and paste action and I got asked, "Could you script do a little reformating, maybe change some links, and maybe some other simple stuff?"

Watch out for these words: maybe, stuff, and simple.

None of the things they asked me to do were complicated on their own (replacing domain names in links, excluding a couple pages, only copying unique attachments, etc) but combined they made my script a monster. After hacking together a script with all of the features shoe-horned in, I was asked to do one more simple task (get a list of the attachment extensions). There was no way to work it into the current script, no easy way to exclude activities from the script, so I was done. For this new feature, I built a separate script we'll have to run separately.

The reason to watch out for those key words is because they communicate with vagueness and leave room for things to be added and removed with little warning. If you start hearing those kinds of general, vague words or, "We'll let you know if we need this or not", "We'll get you a complete list of features later" it's important to politely communicate that if features change, you'd like some extra time to make sure the script you're building is well designed (For this conversation, certain buzz phrases are effective and useful. Phrases like: Reusability, well engineered, software engineering life-cycle).

This is one of my longer posts, and could it be much longer still. It's an important topic if you're building software for a business anywhere.