2.16. 优良习惯#

本节列举一组值得留心的好习惯，推荐您在用 CWL 编写工具或工作流描述时参考。您只需结合实际尽量做到，无需求全。

不要将 type: string 参数用于输入或引用文件、目录的名称；请根据实际情况选用 type: File 或 type: Directory.
CWL 文件（连同 Dockerfile 等外部组件）是一种软件代码。工作流开发人员应明白的是，关于软件许可的通用规则也同样适用于您编写的 CWL 文件。例如，如果您的工作流是公开共享的，则许可条款一定要明确，以便将来的用户了解在什么条件下可以将它运行、修改、或并入其他工作流。因此，请考虑在 CWL 文件中加入 license（许可协议）字段。笔者敦促您选用现成的许可协议，不要独辟蹊径（关于挑选许可协议请参见下文链接）。同时，建议您选取允许任何人重复使用的许可证，如 Apache 2.0.

请尽可能使用 SPDX 标识符指定许可协议。许可协议的元数据字段由形如 https://spdx.org/licenses/[SPDX-ID] 的 URL 构成，其中 SPDX-ID 取自前面链接提到的标识符列表，参见下例这段代码。对于没有 SPDX 标识符的非标准许可协议，请提供许可协议的 URL。

相关阅读：《给科学界程序员的软件许可简明指南》

用 SPDX 标识符指定许可协议的元数据字段示例：
```
$namespaces:
  s: https://schema.org/
s:license: https://spdx.org/licenses/Apache-2.0
# other s: declarations
```
For more examples of providing metadata within CWL descriptions, see the Metadata and Authorship section of this User Guide.
为 CWL 工具或工作流描述的作者添加署名信息。请使用明确、独一无二的标识符，如ORCID.
In tool descriptions, list dependencies using short name(s) under SoftwareRequirement.
为依赖关系添加 SciCrunch 标识符。其格式形如 https://identifiers.org/rrid/RRID:SCR_NNNNNN.
一切 input（输入）和 output（输出）标识符均应体现其概念上的特质。请使用类似 unaligned_sequences、reference_genome、 phylogeny、或 aligned_sequences 这样望文知义的变量名，而非 foo_input、foo_file、result、input、output 等缺乏明确内涵的名称。
In tool descriptions, include a list of version(s) of the tool that are known to work with this description under SoftwareRequirement.
所有输入和输出 File（文件）都需要指明 format（格式）。生物信息学工具应使用来自 EDAM 的格式标识符。另请参考 iana:text/plain、iana:text/tab-separated-values 等在 `$namespaces: { iana: “https://www.iana.org/assignments/media-types/” } 下使用的格式名，以及IANA 媒体类型（又称 MIME 类型）的完整列表。对于非生物信息学工具，请同样运用或创建合适的本体或受控词表 (controlled vocabulary). 如果您对此有经验，请编辑此页面，以告知我们。
将所有能作为流读写（即单次、非随机访问）的输入和输出 File（文件）标记为 streamable: true.
Each CommandLineTool description should focus on a single operation only, even if the (sub)command is capable of more. Don’t overcomplicate your tool descriptions with options that you don’t need or use.
关于自定义类型，每个外部 YAML 文件应与单个类型定义一一对应，以便重复使用。
请使用位于顶级的简短 label（标签）对工具或工作流加以概括。
在用得到的时候，还应添加顶级 doc. 相比上述顶级 label, 此处应提供更长、更详细的描述。
对于有效取值为若干固定值的元素，应使用 type: enum 而非 type: string.
所有用到 JavaScript 之处都应进行评估，考虑是否能将它去除或替代。经常遇到的一例，是处理 File （文件）名称和路径。这时应考虑是否能用 File 的内置属性（如basename、nameroot 和 nameext 等）取代 JavaScript.
写好工具描述后，把它交给同行（最好来自其他机构）进行测试并获取反馈。
若复杂的工作流中包含可以抽象出来的单独组件，应利用 SubworkflowFeatureRequirement 将工作流模块化，以便重复使用其组成部分。
应使软件容器 (container) 符合 Recommendations for the packaging and containerizing of bioinformatics software（《生物信息学软件封装与容器化建议》）一文提出的标准。该文对其他学科也有参考价值。