Files
agent-mkosi/STYLE.md
T
Job79andClaude Opus 5.5 b7bbbf215b chore: install Claude Code from its package repository, add style guide
Replace mkosi.prepare with Anthropic's rpm repository (mkosi.sandbox/),
switch the workflow to the gitea context, and start STYLE.md with a
consistent file header.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 20:08:36 +01:00

1.4 KiB

Style guide

For everyone who changes this repository, people and AI agents alike.

General

  • Keep it simple. Prefer fewer files, fewer lines and the defaults. Delete what isn't needed.
  • Each fact lives in one place. Elsewhere, refer to it by path instead of repeating it.
  • Write plain English in short sentences.

File header

Every file that allows comments starts with a header. It goes after the shebang, if there is one:

#!/bin/sh
# Image version
#
# Prints the build time in UTC (YYYYMMDDhhmm). Every build gets a higher version than the one
# before, which is how systemd-sysupdate tells that an update is newer.
  • Line 1 is a title: a few words, in sentence case, with no full stop.
  • Then a line with only the comment character.
  • Then what the file does and why, naming the files it works with by path.

Files that can't hold comments (JSON, subuid, machine-id) are explained in the file that uses them or in the README.

Comments

  • Explain why, not what. Leave out comments that only repeat the code.
  • Put a comment right above the line or block it is about.
  • Wrap comments at 100 columns.

Shell

  • Use #!/bin/sh with set -eu. Switch to #!/bin/bash with set -euo pipefail only when the script needs bash.
  • Quote variables: "$var".

Config files

  • Put one value per line in lists, with a comment explaining the less obvious entries.