From f4c843b9f7bf1ac84bdcc2e54f6c0aecaa259a98 Mon Sep 17 00:00:00 2001 From: Alexandros Kritikos Date: Mon, 7 Sep 2026 22:00:04 +0300 Subject: [PATCH] =?UTF-8?q?=F0=9F=94=A7=20Updates=20C#=20documentation=20g?= =?UTF-8?q?uidelines=20for=20comments=20and=20logging=20practices?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/instructions/csharp.instructions.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/.github/instructions/csharp.instructions.md b/.github/instructions/csharp.instructions.md index 1d06b3c..9ba5b93 100644 --- a/.github/instructions/csharp.instructions.md +++ b/.github/instructions/csharp.instructions.md @@ -11,7 +11,19 @@ Code style is enforced by `.editorconfig`, `.globalconfig`, and StyleCop analyze - XML doc comments required on all `public` and `protected` members in `src/` (suppressed in `tests/` and `samples/`). - Avoid `null!` (null-forgiving operator) — fix the nullability flow instead of suppressing the warning. +## Comments + +Applies to `src/`. Tests keep the guidance in the testing instructions. + +- **No comments inside member bodies.** Anything worth saying goes in an XML doc comment on the member that says it. +- Document `private` and `internal` members — the analyzers only *require* docs on exposed elements, they do not object to more. Put the "why" in ``. +- If the explanation is about one statement rather than the whole member, extract that statement into a named private method and document that instead. +- For logic inside lambdas or local functions where an XML doc comment is not applicable, extract the logic into a named private method and document that method instead. +- Never state what the code already shows, and never narrate history — a past bug, a change, or an answer to a reviewer belongs in the commit message, where it cannot go stale. +- Sole exception: the justification required beside a narrow analyzer suppression, which has nowhere else to live. + ## Patterns - Prefer **records** for DTOs, value objects, and other immutable data carriers. -- Use `LoggerMessage`-generated `partial` methods on a `partial class` — never log inline (e.g., `logger.LogInformation(…)`). If the containing type cannot be made `partial`, convert it to a `partial class` before adding logger methods. Do not fall back to inline logging. +- Use `LoggerMessage`-generated `partial` methods on a `partial class` — never log inline (e.g., `logger.LogInformation(…)`). Do not make existing types partial without explicit user sign-off. Do not fall back to inline logging. +- If a type cannot be made partial (no user sign-off obtained), do not modify its logging calls — surface the conflict to the user and wait for instruction rather than silently falling back to inline logging. Present at least these options: (1) make the type `partial`; (2) move the `LoggerMessage` methods to a separate type — group reusable messages in one shared class, and keep the rest in a per-type class.