Set Safe Defaults for Flags

This article was adapted from a Google Tech on the Toilet (TotT) episode. You can download a printer-friendly version of this TotT episode and post it in your office.

By Zhe Lu

We all make mistakes. But big mistakes can cause big headaches! Suppose you're writing a utility to update production data for a launch. Before making changes to production data, you want to perform a dry run to validate the expected changes. In your excitement, you forget to include the --dry_run flag in your command:

$ /scripts/credit_accounts --amount=USD10  # Oops, I forgot to include --dry_run

You realize your mistake too late. Safe flag defaults can prevent a simple mistake from turning into a major outage:

Flag has unsafe default:

cliArgs.addBoolFlag(name="dry_run", default=False, help="If set, print change summary, but do NOT change data.") Flag has safe default: cliArgs.addBoolFlag(name="dry_run", default=True, help="If set, print change summary, but do NOT change data.")

Safety depends on context: When defining flags, choose the default that minimizes the cost of potential mistakes. This might involve defaulting to a "dry" run, asking for user confirmation before irreversible actions, requiring a confirmation flag on the command line, or other strategies. If you’re writing documentation that contains commands, always set values to minimize the damage if run blindly:

Flag in documentation has unsafe default:

How to commit changes

Use this command to commit changes. Use --dry_run to test and compute and report changes. shell/scripts/credit_accounts --amount=[value] --filter=[conditions] Flag in documentation has safe default:

How to commit changes

Use this command to compute and report changes. Use --nodry_run to commit the changes. shell/scripts/credit_accounts --amount=[value] --filter=[conditions]

Similarly, consider requiring that environment-specific flags (e.g., backend addresses and output folders) be explicitly set. In this situation, unspecified environment flags will crash your program, instead of potentially mixing configuration across environments.