Skip to content

comments

What this rule does

Controls formatting of # comments — whether a space is required after the #, and how far inline comments must sit from preceding content.

Why this matters

  • Legibility. #comment and # comment read very differently; enforcing a space keeps comments visually distinct from directive-like prefixes.
  • Inline comments. Pushing inline comments away from values prevents visual collisions when values change length; capping the gap keeps them next to the value they describe.

Configuration

[lint.rules.comments]
level = "error"
require-starting-space = true
ignore-shebangs = true
min-spaces-from-content = 2
max-spaces-from-content = -1
Option Default Description
require-starting-space true Require at least one space between # and the comment text.
ignore-shebangs true Skip a line-1 #! shebang or #cloud-config header when require-starting-space is on. yamllint skips only the shebang.
min-spaces-from-content 2 Minimum spaces between code and an inline # comment. Use -1 to disable.
max-spaces-from-content -1 Maximum spaces between code and an inline # comment; -1 (the default) disables it. Must be at least 1 and at least min-spaces-from-content. TOML only.

Spaces and tabs each count as one. Setting max-spaces-from-content reports deliberately column-aligned inline comments, and --fix collapses the alignment.

The rule leaves ytt #@ directives and their inline spacing unchanged on every line. Adding a space after # would turn an instruction into an ordinary comment.

A comment after a block scalar header (key: >- # note) is checked like any other inline comment, where yamllint skips it; see How ryl differs from yamllint.

Examples

✅ Allowed (defaults)

# a properly spaced comment
key: value  # inline comment with two spaces of padding

❌ Reported (defaults)

#missing space after the hash
key: value # only one space before inline comment

🔧 After ryl check --fix

# missing space after the hash
key: value  # only one space before inline comment

❌ Reported (min-spaces-from-content = 2, max-spaces-from-content = 2)

first: value        # too far from its value
second: value # too close

🔧 After ryl check --fix

first: value  # too far from its value
second: value  # too close

Automatic fixing

ryl check --fix inserts the missing space after #, pads inline comments to the configured min-spaces-from-content, and replaces a gap wider than max-spaces-from-content with that many spaces. Disable with:

[lint]
fixable = ["ALL"]
unfixable = ["comments"]

ryl format follows [format] comment-starting-space and comment-spacing (defaults "add" and 2). It conflicts when the configured comment gap falls outside the lint spacing bounds; see Conflicting lint rules.