One-Off Script Writing: Key Tips for Success

Here’s the situation: your team recently added a new feature that requires migrating database schemas and data. To make it more challenging, the database you’re using doesn’t support transactions.

The migration seems simple, so you decide to write a quick, rough script in one morning to complete the task. After all, the script will run only once, and only you will execute it.

What could possibly go wrong? ¯\_(ツ)_/¯

Defenseless programming: a recipe for disaster

One-off scripts often receive little attention because they are meant to be disposable. As a result, developers are often tempted to skip many best programming practices, leading to no tests, no documentation, and generally low-quality code.

In programming, anything that can go wrong will eventually go wrong. Here’s a list of scenarios that are likely to happen. Notice how low-quality code leaves you unprepared to confidently handle these situations successfully.

• The script will run more than once. First, you’ll migrate your staging environment, then your development environment, and finally your production environment.

• Your teammates will also run your script without your supervision. On the day the team needs to migrate the database in the production environment, you might be on vacation or out sick.

• The database doesn’t support transactions. If the migration fails, the database can become corrupted, unusable, and unrecoverable.

• Migration will work well in the staging and development environments but will likely fail in the production environment due to an unexpected edge case. Users of your service will face downtime until the database is restored.

• Be prepared to clearly and confidently explain to your teammates why the migration failed, the current state of the database, and how to move forward, all without rerunning the script.

• Be prepared to clearly and confidently explain these conclusions to your manager. They need to understand what happened so they can inform the users of the service, depending on how critical your service is.

Defensive Programming: 10 Tips to Master It

By understanding the scenarios you might face, you can write code that safeguards you in each situation and equips you with the tools needed to handle these issues effectively.

First, you will run tested code confidently, with little chance of making mistakes. Second, your teammates will trust your work because you have minimized risks and understand how to handle emergencies. Your manager, who is also your teammate, will trust you too, as you understand their role and provide clear, valuable explanations that help them communicate with end clients effectively.

In the end, being a senior developer is much more than just writing clean code. Valuable senior developers consider the needs of all team members in their work, which gives confidence to everyone on the team.

Here are 10 tips to greatly improve your one-off scripts. For each tip, take a moment to consider how it can help you handle the situations mentioned earlier.

1. Upload your code to a version control repository. The README.md should include clear instructions for installing dependencies and running the code.

2. Write code that is clean, easy to follow, and understandable for your future self and your teammates. It may not be the best piece of art since it is a one-off task, but it must be easy to work with.

3. Document the detailed technical steps of the migration in simple language on your ticketing platform, and use the same explanations in the code documentation. This way, you won’t have to figure out what the code does by reading through all the implementation.

4. Test the key steps of your migration using either unit tests or integration tests. By testing your code, you will know that it works. With tests, you will catch bugs before they hit into production database. Code without tests is broken by design.

5. Add a command-line interface (CLI). You should be able to configure the execution settings using argument parameters and flags. Avoid opening files to change any global variables or commenting out sections of code.

6. Migration should run with --dry-run enabled by default. The script will only commit changes to the database if you explicitly set the --no-dry-run flag.

7. If possible, provide a relevant summary of the resources that will be migrated before the migration takes place. Useful plans include statistics on the number of resources affected by the migration, the number of resources unchanged, and lists of data inconsistencies that need to be fixed before applying the migration, among others.

8. Use a library that provides complete information about the context of a failure. Migrations are usually not idempotent, so you need to know the exact reason why the migration failed without having to rerun the script. For example, in Python, Typer is a CLI that logs detailed information about an exception’s context, including the values of variables at each level of the stack trace.

9. Back up your data right before the migration. If possible, run the migration on a copy of the production database before migrating the original one.

10. Log the progress of the migration so you can see if it is proceeding correctly or if it gets stuck at any point.

Conclusion

When writing one-off scripts, it’s important to follow best practices, even if they are temporary. These scripts should be developed using good programming practices. These practices will help you and your teammates, ultimately building strong and valuable trust relationships.

(•_•)

( •_•)>⌐■-■

(⌐■_■) Happy coding!