Command names

From ProgClub
Revision as of 00:22, 11 June 2020 by John (talk | contribs) (→‎Standard)
Jump to: navigation, search

I am eminently unqualified to for this job. But I needed to figure out if I was going to write a backup script for my database server 'unity', was I gonna name my backup script 'unity-backup.sh' or 'backup-unity.sh'. They say that form is liberating, and I believe them. So I wanted to develop some guidelines which can help me in such matters.

These are my nascent thoughts on naming things, specifically naming Linux commands which will be issued in a console. The "grammar" described here might not yet be sufficiently powerful; this is a work in progress and these are just first thoughts. If you have suggestions for me I would be very pleased to hear them, feel free to get in contact.

Standard

Command names must be all lower case and can contain alphanumeric ASCII characters and dash (-) and dot (.), but they must not start or end with dash or dot.

If the command is implemented as a BASH function or a BASH alias then the name has no suffix (and no dots). Otherwise the command suffix will indicate the implementation with a suffix (file extension) that is typically '.sh' for BASH scripts and '.php' for PHP scripts and so on for your weapon of choice. Yes this leaks an implementation detail into the interface, and yes we're gonna do that anyway. Generally a script with a file extension as a suffix provides less guarantees of interface stability than function/alias commands.

Commands which are scripts should start with a shebang on the first line and be chmod'ed +x. Use /bin/bash for BASH and /usr/bin/env php for PHP.

If the command operates on only a single "hardcoded" noun then the command name is in the form noun-verb. Otherwise if the command operates on an arbitrary noun taken as a parameter then the command name is in the form verb-noun.

If you have a hardcoded noun which you can operate on for a variable noun then the format is noun-verb-noun.

If you have a process that operates on multiple nouns you can "stack" them "containerwise". E.g. a database server contains multiple databases so if you were to operated on a particular database on a particular server the name would be $process-$server-$database (as verb-noun-noun).

Rationale

Why include a suffix?

Basically so you can reimplement and phase out gradually.

Also it's nice to know a little bit more about what you're dealing with when you use it.

And when there's only one implementation the suffix is just one auto-complete TAB away.

And if you do reimplement using a different technology if you have interface parity you can simply alias the old command name and *lie* about the implementation.

Implementation

As we said scripts should end with a suffix but functions/aliases should not. To be consistent here if you want to expose a new command for users and you don't want the implementation details to shine through then you should implement your command as a BASH function or BASH alias and use that implementation to defer to the actual script (with its suffix) that does the actual work.

Examples

Database backups

So we have a database server called 'unity' which has a bunch of databases with various names.

The name of the script which can backup any MySQL/MariaDB database server (indicated with a command argument) is called 'backup-mysql.sh'.

The name of the script which backs up 'unity' is 'unity-backup.sh' (because it only operates on 'unity').

The name of the script which can restore a database backup to any MySQL/MariaDB database server is called 'restore-mysql-database.sh', notice that nouns stack "containerwise" (i.e. the "MySQL/MariaDB" server contains the "database", so the container is listed first in the noun list).

The name of the script which can restore a specific database backup to 'unity' is called 'unity-restore.sh'.