annofab-cli-command-style

name	annofab-cli-command-style
description	annofab-cli のコマンド名、オプション名、引数名、help文、CLIの振る舞いに関する規約に従って実装・修正するときに使用。

命名規則

• コマンドは辞書順に並べる。
• コマンド名はアンダースコア区切り
• オプション名はアンダースコア区切り

ヘルプメッセージ

• コマンドライン引数のデフォルト値は自動で出力されるので、help引数にデフォルト値を明記しない。

コマンドの振る舞い

• 複数リソースを処理するコマンドは--parallelismを用意する。ただし、プロジェクトに対する操作や削除処理など、間違えて処理したときの被害が大きいコマンドは--parallelismを用意しない。
• CSV出力するコマンドでは、出力件数が0件でもヘッダ行を出力する。

複数件のリソースを処理する際のログ出力

• 何件目を処理しているかをログに出力する。
• 100件や1000件など、適当な件数ごとに進捗をinfoレベルでログに出力する。
• 全部の処理が完了した後に、成功件数、スキップ件数、失敗件数などのサマリをログにinfoレベルで出力する。
• try-exceptでエラーをキャッチした場合は、logger.warning(..., exc_info=True)を使って、スタックとレースも出力する。

ログレベル

• warning: ユーザーにとって想定外の事態が発生した場合
  • エラーをキャッチして、かつ処理を継続できるとき
  • 更新対象のリソースが存在しないとき
  • 入力値が不正なとき
• info: ユーザーにとって有用な情報を提供する場合
  • コマンドの開始、終了
• debug: 細かく進捗を把握するのに役立つ情報
  • 各リソースの情報
  • 各リソースごとに成功したという情報