Decide on when to provide a --help flag for bash scripts

[jotaen4tinypilot]

Our bash scripts currently don’t follow a consistent pattern in regards to whether they provide a --help option. E.g.,

• the change-hostname privileged script has it, whereas
• the read-update-log privileged script doesn’t have it.

My suggestion would be:

• If a bash script is supposed to be user-facing, then it should provide a --help flag.
  • For instance: all scripts in the /opt/tinypilot/scripts folder.
  • The docstring summary at the top (such as this one) is then probably obsolete, unless it provides extra information.
• If a bash script is for internal purposes (i.e., programmatic usage), it shouldn’t provide a --help flag.
  • For instance: all our privileged scripts.
  • However, a docstring comment at the top should then be mandatory.

The downside of providing a --help flag is the significant amount of boilerplate code it requires. To illustrate this: is-ssh-enabled has 24 LOC – only 6 of which are actual logic, and 18 are for processing the --help flag.

[mtlynch]

I agree. I like the proposed convention.