Skip to main content

Scalars, Lists, Nullability, and Defaults

Small type decisions shape the caller's first experience with a module. Required strings, optional booleans, default paths, and list arguments all communicate what the caller must know.

Scalars​

Use scalar values for simple facts:

  • Names.
  • Versions.
  • Tags.
  • Flags.
  • Counts.
  • Modes that are genuinely open-ended.

Avoid using strings as untyped containers for paths, credentials, structured configuration, or closed choices. If Dagger has a more precise type, use it.

Lists​

Use lists when the caller naturally thinks in collections: targets, platforms, files, packages, checks, or tags.

List arguments should explain:

  • Whether order matters.
  • Whether duplicates are accepted.
  • What happens when the list is empty.
  • Whether a default list comes from the workspace.

Nullability​

Required values should be truly required. Optional values should have clear behavior when omitted.

Use optionality to mean "the module can choose a sensible behavior without this input." Do not use optionality to avoid deciding what the API means.

Defaults​

Defaults should encode common intent, not hidden magic.

Good defaults:

  • Make the common call short.
  • Are documented in argument help.
  • Come from workspace settings when the default is team-specific.
  • Keep file and directory scopes as narrow as possible.

Bad defaults:

  • Read the whole workspace by accident.
  • Depend on host environment state.
  • Change behavior silently across contexts.
  • Hide credentials or network dependencies.

Writing Assignment​

TODO: Add a prose example that compares a noisy function with too many required scalar arguments to a cleaner function using defaults, settings, and stronger Dagger types.