Files
agent-mkosi/STYLE.md
T
Job79andClaude Opus 5.5 a1fc65ed21 style: apply STYLE.md to all files
Give every file a header (title, empty line, explanation), wrap comments
at 80 columns and keep them to the why. Only comments change.

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

31 lines
1.0 KiB
Markdown

# Style guide
- 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:
```sh
#!/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 80 columns.