2.16. ベストプラクティス#

以下は、ツールやワークフローのCWL定義を書く際に留意すべき推奨グッドプラクティスのセットです。これらのガイドラインは、有用性の尺度で検討するために提示されています：多ければ多いほど良いが、すべてが必要なわけではありません。

入力または参照のファイルやディレクトリの名前に type: string を使用しません。 type:File または type: Direcotry を適宜使用します。
CWL 定義（Dockerfileのような外部コンポーネントと合わせて）は、ソフトウェアコードです。ワークフロー開発者は、ソフトウェアライセンスに関する通常の規則がこのCWL定義に適用されることを認識する必要があります。例えば、ワークフローが一般に共有される場合、将来のユーザーがどのような条件でワークフローを実行、修正、および/または他のワークフローと組み合わせることができるかを理解するために、ライセンス条項は明確でなければなりません。このような理由から、CWL定義にライセンスフィールドを含めることを検討してください。このガイドの著者は、独自のライセンスを作成するのではなく、既存のライセンスを選択することをお勧めします（ライセンスの選択について詳しくは、以下のリンクを参照してください）。そして、私たちの推奨する実践は、誰でも再利用できるライセンスを選択することです。例えば Apache 2.0です。

可能であれば、ライセンスは対応する SPDX 識別子と共に指定されるべきです。https://spdx.org/licenses/[SPDX-ID] (SPDX-ID は、上記のリンク先の識別子のリストから選択) という形式の URL を指定して、ライセンスのメタデータフィールドを構築します。以下の例を参照してください。SPDX識別子のない非標準ライセンスの場合は、そのライセンスへのURLを指定します。

参考文献："A Quick Guide to Software Licensing for the Scientist-Programmer"

SPDX 識別子を持つライセンスのメタデータフィールドの例：
```
$namespaces:
  s: https://schema.org/
s:license: https://spdx.org/licenses/Apache-2.0
# other s: declarations
```
CWL定義にメタデータを与える例については、このユーザーガイドのメタデータと著者名のセクションを参照してください。
CWLツールやワークフローの定義の著者の帰属情報を含みます。ORCIDのような曖昧でない識別子を使用してください。
ツール定義では、SoftwareRequirement.の下に、短い名前を使用して依存関係をリストアップします。
https://identifiers.org/rrid/RRID:SCR_NNNNNN 形式で依存関係のための SciCrunch 識別子を書きます。
input およびoutput の識別子はすべて、その概念的同一性を反映する必要があります。foo_input,foo_file,result,input,output, などの代わりにunaligned_sequences,reference_genome,phylogeny, またはaligned_sequences などの情報量の多い名称を使ってください。
ツール定義では、SoftwareRequirementの下に、このツール定義で動作することが確認されているツールのバージョンのリストを書きます。
format は、すべての入力および出力Fileに指定する必要があります。バイオインフォマティクスツールは、EDAMのフォーマット識別子を使用するのが良いです。iana:text/plain,iana:text/tab-separated-values、$namespaces：{ iana: "https://www.iana.org/assignments/media-types/" } も参照してください`.IANA メディアタイプ一覧（MIME タイプとしても知られています）。バイオインフォマティクス以外のツールについては、同様に適切なオントロジー/統制語彙を使用または構築してください。このページを編集して私たちに知らせてください。
Fileの入出力のうち、ストリーミング互換の方法（一度だけ利用されて、ランダムアクセスなし、訳注標準入出力のイメージ）で読み書きされるものを、streamable: true としてマークします。
各CommandLineTool の定義は、たとえ（サブ）コマンドがそれ以上の機能を備えていたとしても、一つの使用方法のみに焦点を当てるべきです。必要ないまたは、使用しないオプションでツールの定義を複雑にし過ぎないようにしましょう。
カスタム型は、型定義ごとに1つの外部YAMLで定義すると再利用しやすくなります。
ツール/ワークフローを要約したトップレベルの短いlabel を含めます。
有用であれば、トップレベルdoc も含めてください。これは、トップレベルlabel （上記参照）で提供されたものより長く詳細な説明を記述します。
有効な値のリストが決まっている要素には、type: string の代わりに、type: enum を使用してください。
JavaScriptのすべての使用について、削除または置換の可能性を評価します。よくある例：File の名前とパスを操作する方法は？basename,nameroot,nameext, などのビルトインFile プロパティのいずれかを代わりに使用できないか考えてみてください。
ツール定義を同僚（できれば別の機関の人）に渡し、テストしてもらい、フィードバックをもらいましょう。
抽象化できる個々のコンポーネントを持つ複雑なワークフローは、ワークフローをモジュール化し、その一部を容易に再利用できるようにするために、SubworkflowFeatureRequirementを利用します。
ソフトウェアのコンテナは、"Recommendations for packaging and containerizing of bioinformatics software" に準拠するようにします（他の分野でも有用です）。