From 044d9b5594e2c7b6c3f48591c299ae100eaf83e5 Mon Sep 17 00:00:00 2001 From: tiennm99 Date: Thu, 17 Sep 2026 09:44:12 +0700 Subject: [PATCH] docs: keep rationale in READMEs, not in compose files and Dockerfiles MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Comments say what a section installs or configures. Why not the distro package, why that directory, why a version is pinned — that belongs in the service README, where it can be read in full. Replaces the line under "Installing software in an image" that asked for the opposite. --- CLAUDE.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 2490e2e..e654a44 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -20,8 +20,18 @@ community installer. Do not hand-roll a download, and do not take a stale distro package just because `apt install` is shorter — check what version it actually gives you first. -State the reason in a comment when the obvious route is the wrong one, so the -next person does not "simplify" it back. +## Comments in compose files and Dockerfiles + +A comment says *what* a section installs or configures, in a line or two. It +does not explain *why*. Reasons — why not the distro package, why that +directory, why a version is pinned, what would break if it were simplified — +go in the service's `README.md`, where they can be read in full and where +someone deciding whether to change something will actually look. + +So: no rationale, no trade-offs, no cautionary notes in the file itself. When a +choice needs defending, write the defence in the README and let the header +comment point at it. Keep the README current whenever a file changes, otherwise +the reasoning is simply lost rather than relocated. The root `README.md` is an index only — it covers the shared conventions and links out to each service. Per-service detail (variables, ports, storage)