From 91440326d7bdcc3e6892599c8c7fdd3235ff1a53 Mon Sep 17 00:00:00 2001 From: Dominik Jain Date: Mon, 21 Sep 2026 13:13:36 +0200 Subject: [PATCH] Improve instructions on comments --- .serena/memories/critical_info.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/.serena/memories/critical_info.md b/.serena/memories/critical_info.md index c40068f5..700c57b6 100644 --- a/.serena/memories/critical_info.md +++ b/.serena/memories/critical_info.md @@ -25,14 +25,24 @@ Snapshot tests use syrupy. # Docstrings & Comments +Documentation style: + * You consistently use reStructuredText. * You structure function implementations into functional blocks that are separated by blank lines. Atop each functional block, you write an elliptical phrase (starting with lower-case letter) that describes the purpose of the block in a concise manner. * When describing parameters, methods/functions and classes, you use a precise style, where the initial (elliptical) phrase clearly defines *what* it is. Any details then follow in subsequent sentences. + +General documentation principles: + * Each piece of information appears exactly once, at the element that owns it: callers do not explain callees' internals, and callees do not describe their callers. +* Code changes are documented exclusively in commit messages, not in comments. +* Things you consequently avoid: + - For a function/class, you do not describe who calls/uses it. A call/usage site may explain why a usage occurs, but only if it is non-obvious. + - When a function is called, you do not describe what it does. That belongs in the function's docstring. + - You do not describe in comments how an implementation differs from a previous state of the code or why a change was made. That belongs in the commit message. # REPL & facades