Skip to main content
Version: 0.21.7

Function Arguments and Return Values

A function signature is the caller's contract. It says what the caller must provide, what the module promises back, and how the result can be used next.

Arguments​

Every argument should answer one question for the caller.

Prefer:

  • Specific Dagger types over strings.
  • Defaults for project conventions.
  • Settings for workspace-level defaults.
  • Secrets for credentials.
  • Directories and files for content.
  • Enums when only a known set of values is valid.

Avoid:

  • Options bags that hide many concepts in one string.
  • Magic environment variables.
  • Host path assumptions.
  • Arguments whose meaning changes by context.

Return Values​

Return the richest useful value. A function that builds an image may return a Container; a function that generates code may return a Changeset; a function that computes metadata may return a structured object.

Avoid flattening everything into a string just because it is easy to print.

Writing Assignment​

TODO: Add an API review checklist for arguments and return values: requiredness, defaults, type precision, cache scope, secret handling, side effects, and composability.