CWL style guide

CWL_style_guide.md

Building off of the CWL Recommended Best Practices

1. Use label: to describe what happens in steps:

class: Workflow

label: A workflow to do 1. 2. 3.

steps:
  module_1_innovation:

2. Name inputs with program__parameter_name

e.g.

md__assume_sorted: true

3. Create reusable sub workflows to prevent overly-long .cwl files:

  compute_bam_metrics_1:
    run: ./waltz/waltz-workflow.cwl <-- Using the same workflow 2x
    in:
      input_bam: previous_step_1/bam
    out: [pileup, waltz_output_files]

  compute_bam_metrics_2:
    run: ./waltz/waltz-workflow.cwl <-- Using the same workflow 2x
    in:
      input_bam: previous_step_2/bam
    out: [pileup, waltz_output_files]

4. File vs string types

Use File if you're dealing with a file, not a string. This will give better validation, and allow for cloud-based file storage such as s3:// or gs://

5. Use consistent spacing. Organize inputs logically

<single newline between workflow properties (inputs, outputs, steps)>
inputs:
<single newline after header for workflow property with many children>
  title_file: File
  fastq1: File[]
  fastq2: File[]
  sample_sheet: File[]
<single newlines to group inputs into logical sections>
  reference_fasta: string
  reference_fasta_fai: string

  # Marianas Clipping
  umi_length: int
  output_project_folder: string

  # Module 1
  adapter: string[]

6. Use more concise syntax if available:

Prefer type: File[] as opposed to:

type:
  type: array
  items:
    type: File

Prefer type: string? as opposed to:

type:
- 'null'
- string

Prefer simpler valueFrom syntax

    java_8:
      valueFrom: $(inputs.run_tools.java_8)

instead of

    java_8:
      valueFrom: ${return inputs.run_tools.java_8}