From e1ac8ae49a8954060fe70d364200da5d3afce6f7 Mon Sep 17 00:00:00 2001 From: "F.N. Claessen" Date: Sat, 1 Aug 2026 12:16:47 +0200 Subject: [PATCH] chore: reinforce the docstring/comment line-break convention for agents The 'break lines only after punctuation' rule is deliberate but easy to miss, and code reviewers (Copilot included) sometimes suppress mid-phrase-break findings as low-confidence. - docstrings.instructions.md: state the rule more explicitly, and instruct reviewers to always surface a mid-phrase break (do not suppress it as low-confidence). - Add a CLAUDE.md so Claude Code sessions pick up the .github/instructions conventions (Claude reads CLAUDE.md; the Copilot instruction files are not auto-loaded by it), with the line-break rule called out. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01TaMepbxRYzJxQKFtu6Hq4p Signed-off-by: F.N. Claessen --- .../instructions/docstrings.instructions.md | 6 ++++- CLAUDE.md | 24 +++++++++++++++++++ 2 files changed, 29 insertions(+), 1 deletion(-) create mode 100644 CLAUDE.md diff --git a/.github/instructions/docstrings.instructions.md b/.github/instructions/docstrings.instructions.md index 59e97b848a..689d014efe 100644 --- a/.github/instructions/docstrings.instructions.md +++ b/.github/instructions/docstrings.instructions.md @@ -35,7 +35,11 @@ def function_name(param1: str, param2: int) -> bool: - Use `Example::` (double colon) to introduce a doctest block. - Complement type hints — don't duplicate them in the docstring text. - Use exactly one space after punctuation (no double spaces after periods). -- Use line breaks only after punctuation (this facilitates review commenting and text searching). This applies to in-line comments as well, not only docstrings; keep in-line comments short. +- Use line breaks only after punctuation (this facilitates review commenting and text searching). This applies to in-line comments as well, not only docstrings; keep in-line comments short. So never wrap a docstring or comment in the middle of a phrase; each physical line must end at a comma, semicolon, colon, or period. (E501 is ignored and `max-line-length` is 160, so a long clause on one line is preferred over a mid-phrase break.) + +## For code review (incl. automated reviewers) + +The line-break-after-punctuation rule above is a deliberate, load-bearing convention (stable review comments and text search), not a stylistic nicety. When reviewing a change, always report a docstring or comment that wraps mid-phrase as a review comment; do not treat such a finding as low-confidence, and do not omit or suppress it. ## Click CLI commands diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000000..33fd4af42d --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,24 @@ +# FlexMeasures — conventions for coding agents + +The repo's cross-cutting conventions live in [`.github/instructions/`](.github/instructions/) as +`*.instructions.md` files (their `applyTo:` frontmatter maps them to file globs). They are written +for GitHub Copilot, but they are the source of truth for **any** agent working here — read the ones +relevant to the files you touch, and follow them. + +Most-missed rules, called out so they are not forgotten: + +- **Docstrings & comments break lines only after punctuation** — never wrap in the middle of a phrase. + Each physical line ends at a comma, semicolon, colon, or period. `E501` is ignored and + `max-line-length` is 160, so prefer a long clause on one line over a mid-phrase break. This keeps + review comments and text search stable. See [`docstrings.instructions.md`](.github/instructions/docstrings.instructions.md). +- **Run the pre-commit hooks before committing** — they reformat (black), lint (flake8), type-check, + and regenerate the OpenAPI spec; a hook that rewrites a file aborts the commit, so re-stage and + commit again. See [`pre-commit-hooks.instructions.md`](.github/instructions/pre-commit-hooks.instructions.md). +- **Add a changelog entry** for user-facing changes, in the right section, with a PR link. See + [`changelog.instructions.md`](.github/instructions/changelog.instructions.md). +- **One logical change per commit** ([`atomic-commits.instructions.md`](.github/instructions/atomic-commits.instructions.md)), + **timezone-aware datetimes always** ([`timezone-awareness.instructions.md`](.github/instructions/timezone-awareness.instructions.md)), + **catch specific exceptions** ([`error-handling.instructions.md`](.github/instructions/error-handling.instructions.md)), + and **"organisation" not "account" in user-facing text** ([`ui-terminology.instructions.md`](.github/instructions/ui-terminology.instructions.md)). + +When you add a docstring or comment, re-read it against the line-break rule before moving on.