Commenting

Code should be self-documenting. Prefer:

• ✅ Well-named functions and variables
• ✅ Clear types
• ✅ Tests documenting behavior
• ❌ Inline comments explaining obvious code
• ❌ TODO comments (use issues)
• ❌ Commented-out code

• Code is the source of truth — comments can become stale
• Well-named functions explain what they do
• Types document parameters and returns
• Tests document expected behavior
• Git history tracks why changes were made

// CreateBackup creates a backup of the given stack.
// If includeVault is true, vault secrets are included.
func (s *Service) CreateBackup(
    ctx context.Context,
    stack string,
    includeVault bool,
) (*BackupManifest, error) {
    ...
}

// Bad: comment explains code
// ZFS requires unmount before snapshot
s.unmountDataset(dataset)

// Good: function name is self-explanatory
s.unmountForZFSSnapshot(dataset)

Track work in issues, not code.

Use git history if you need to recover old code.

The only acceptable inline “comments” are:

1. Linter directives:

//nolint:errcheck // fire-and-forget logging

2. Brief explanations of non-obvious behavior:

// SQLite requires this order due to FK constraints

Configure linters globally in .golangci.yml rather than using per-file directives when possible.