From a74a1ab1360c87796af8bf3bddd2319e9d58bf3e Mon Sep 17 00:00:00 2001 From: Ansh Roboto Date: Tue, 21 Jul 2026 14:06:42 +0530 Subject: [PATCH] promote(org): comments-explain-why --- entries/org/comments-explain-why.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 entries/org/comments-explain-why.md diff --git a/entries/org/comments-explain-why.md b/entries/org/comments-explain-why.md new file mode 100644 index 0000000..17ef540 --- /dev/null +++ b/entries/org/comments-explain-why.md @@ -0,0 +1,7 @@ +--- +description: Never write a comment explaining what the code already says — comment only what a reader cannot recover from the file +type: standard +author: anshroboto +date: 2026-07-21 +--- +Never write a comment that explains what the code already says — a paraphrase of the lines under it, a value visible in the diff (`// 4px to match Figma` belongs in the ticket), a section signpost, a restated signature, or an attribution of a change. Comment only what a reader cannot recover from the file: discovered external-system behaviour, a workaround with a link and a removal condition, a non-obvious invariant or ordering constraint. AI diffs narrate every block by default; hold them to the same bar.