Skip to content

Latest commit

 

History

History
73 lines (70 loc) · 5.15 KB

style-guide.md

File metadata and controls

73 lines (70 loc) · 5.15 KB
Raw

WDL Style Guide

All rules below should be followed by contributors to this repo. Pull Requests which do not conform to these specifications will be asked to change.

Rules

  • Files should have an SPDX formatted Copyright and License information at the top of the page, but below any wdldoc header lines (lines starting with ##)
    • If copyright and license comments are preceeded by wdldoc header lines, there should be an empty comment line (#\n) between them
  • The WDL version declaration should immediately follow copyright and license comments, without any lines separating them
  • All import statements should follow the WDL version declaration (with one empty line between the version and the first import statement)
  • Import statements should be sorted by the lexicographical ordering of each line
    • No extra white space allowed between symbols or lines
  • Variables, tasks, and workflows should be in lowercase "snake_case"
  • Declared structs should be in "PascalCase"
  • For workflows, the following sections must be present and in this order: meta, parameter_meta, input, output
    • input, parameter_meta, and output are technically optional in the WDL spec, though it is discouraged to write workflows in this manner.
      • If input is present, then parameter_meta must also be present
  • For tasks, the following sections must be present and in this order: meta, parameter_meta, input, command, output, runtime
    • input, parameter_meta, and output are technically optional in the WDL spec, though it is discouraged to write tasks in this manner.
      • If input is present, then parameter_meta must also be present
  • The meta section should have a description of the task or workflow
    • The description should be in active voice, beginning the first sentence with a verb
      • Each task/workflow is doing something. The first sentence should be a succinct description of what that "something" is.
  • The meta section should have an outputs key and keys with descriptions for each output of the task/workflow
  • Additional meta entries are allowed (such as author or email keys)
  • All inputs must have a corresponding parameter_meta entry
    • These texts should be copy and pasted from other tasks with the same input when possible
    • Inputs and parameter meta must be in the same order
    • 3 high level input sections
      • first are required inputs
      • second are optional inputs
      • last are inputs with a default value
    • within each section, inputs are ordered by variable type
      • File
      • Array[*]+
      • Array[*]
      • struct
      • Object
      • Map[*, *]
      • Pair[*, *]
      • String
      • Boolean
      • Float
      • Int
    • for ordering of the same compound type, drop the outermost type and recursively apply above sorting
    • once the above ordering is satisfied, it is up to the developer for final order of inputs of the same type.
    • Disallowed input names: /^[iI]n[A-Z_]/, /^input/i
      • It is redundant and needlessly verbose to use an input's name to specify that it is an input
  • If documenting a workflow, task, input, or output and you need to be more verbose than is appropriate in a description: field, you may include in addition an external_help: key with a URL
    • external_help is not a substitute for internal documentation, although it may allow the internal documentation to be briefer
  • command blocks should be wrapped with arrows (<<< >>>) instead of brackets ({ })
    • Certain Bash constructions cause problems with the bracket notation
  • output variable names should be short but descriptive
    • Disallowed output names: /^[oO]ut[A-Z_]/, /^output/i, /^..?$/
      • It is redundant and needlessly verbose to use an output's name to specify that it is an output
  • All tasks should run in a persistently versioned container
    • This ensures reproducibility across time and environments
  • no whitespace on empty lines
  • no whitespace at the end of lines
  • indentation should be 4 spaces and never tab literals
  • At most one empty line in a row
  • There should be an empty line between workflow/task sections and any intermediate declarations
  • End the file with a newline
  • Comments on the same line as code should have 2 spaces before the # and one space before the comment
  • Files should not mix \n and \r\n line breaks
  • WDL lines should be less than 90 characters wide whenever possible
    • Exceptions would be long strings that WDL doesn't allow to be broken up
    • This restriction applies to embedded code in the command block as well.
  • Any tasks which are deprecated should have a deprecated: true key in their meta section
    • It is allowed (but redundant and discouraged) to include a deprecated: false key in any production tasks. All tasks are assumed to not be deprecated unless otherwise noted.
    • In addition, the description key of deprecated tasks should start with **[DEPRECATED]**
      • These two rules allow for a task's deprecated status to be communicated in multiple ways, ensuring no user misses the notice
  • Deprecated tasks should be placed at the end of their file