Loading

命令行接口设计

前面

命令行程序我们平常或多或少都用过一些，比如日常使用的一些linux命令，专业领域内的一些命令行程序等。大家大致都了解一些，但这里还是先说几个概念。 主要是为了解释下"argument", "option" 和"parameter"。不过这几个词在不同的应用场景下，可能意思并不相同，这里主要还是说在bash shell下运行命令的语义。

#如cp的用法如下
#  cp [OPTION]... [-T] SOURCE DEST
cp -f test1.txt test2.txt

# wc [OPTION]... [FILE]...
wc -l tmp.py

# cut OPTION... [FILE]...
cut -f 1 test.txt

command name
命令名字，代表你想要运行的程序，在上面的例子中， cp, wc,cut就是命令名字。为了避免歧义，出现command 指"wc -l tmp.py" 还是指"wc", 这种问题。下文统一将程序名视作command name, 而command 指包含程序名+参数。
argument **
针对BASH而言，argument 指command name 后面的字符, 都可以称为argument , 但是有些argument 有其更特别的名称。对于我们日常使用，也许是指positional parameter, 对于cp 命令，argument 指SOURCE和 DEST，具体运行时，argument 参数值是test1.txt test2.txt。
option**
也有称 flag，指那些字符前有"-"或者"--"的**argument ,通常影响着命令的输出。如-f, -l 等
parameter 实际传递给程序argument /option **的值，是可变的，中文，或许可以说成参数值。

这里大致简单区分下就行，实际情况里，结合上下文具体判断下实际意思。比如Python中的命令行解析库argparse，不管可选参数还是位置参数, 统一都用**add_argument **方法进行添加。而click库，就有明确的区分，可选参数是option， 位置参数是argument。

设计

help text and Documentation

一个命令行软件不可缺少的help文本提示，只有这样，才能让人快速即时了解程序如何运行。

  1. 当运行程序添加-h/-help **option **运行时，展示帮助文本。帮助文本内容：
    1. 提供反馈和问问题的地址，比如github
    2. 程序完整的文档链接
    3. 提供运行示例，但不要太多，更多的应放在文档内。
    4. 将最常用的options展示帮助文本的开头
    5. 帮助文本格式便于阅读
  2. 当直接运行程序时，展示简要的帮助文本，让人可以快速使用程序。这份简要帮助文本应包含一下内容：
    1. 程序功能描述
    2. 一两个示例
    3. 主要options描述
    4. 提示传入--help option可以获取更多帮助文本
  3. 提供基于web和终端的文档

Arguments/options

  1. options，提供短名和长名两个版本如-h/--help
  2. 尽可能为Arguments/options提供最优默认参数值
  3. 当运行结果会导致危险结果时，提供确认选项
  4. 当参数值是文件地址时，支持从stdin 读取和输出到stdout

naming

命令行程序需要通过打字输入控制运行，程序参数命名极为重要

  1. 命名应尽量简单，易记。
  2. 只使用小写
  3. 命名尽量简短
  4. 易于输入
  5. 使用一些标准或者约定熟成大家都懂的名字
    1. -h/--help 表示输出帮助文本
    2. -a/--all 表示所有
    3. -o/--output 输出
    4. ......

Subcommands

  1. 如果程序足够复杂，可以使用子命令来完成不同的功能
  2. 不同子命令的Arguments/options 命名应该一致

Robustness

  1. 验证用户的输入
  2. 对于长时间任务，优先提供响应输出，例如先打印一些信息
  3. 对于长时间任务，提供进度条

Output

  1. 程序输出应该优先人类可读
  2. 默认情况下，不要输出一些仅由程序开发者才能看懂的信息
  3. 当输出长文本时，考虑使用pager(例如 less)
  4. 当用户输入错误的命令时，输出一些正确命令给用户参考
  5. 不要将**stderr **视为 log file，至少不要当作默认设置。
  6. 不要打印出log等级标签（ERR, WARN, etc.）
  7. 除非在verbose模式下，不要输出额外的上下文信息

Error

将一些常见运行错误，放在文档里，可以节省用户许多时间。

  1. 将错误，以更人类化的形式输出
  2. 将更为关键的信息优先呈现出来，控制信噪比，考虑将多余信息输出到日志文件而不是直接输出在终端
  3. 提供用户反馈提交bug的链接

development

使用现有成熟的的命令行解析库进行开发，这回节省许多的时间，让你更多时间专注于程序功能开发。以下是一些参考：

  • Python: Argparse, Click, Typer
  • R: argparse,
  • Bash: argbash
  • Ruby: TTY

以上更多的只是一些参考，实际中有时也不能完全遵守。

参考

https://clig.dev/#guidelines
http://lh3.github.io/2021/07/04/designing-command-line-interfaces
https://stackoverflow.com/questions/36495669/difference-between-terms-option-argument-and-parameter

posted @ 2022-03-27 16:25  何物昂  阅读(195)  评论(0)  编辑  收藏  举报