From f7d06e953368601ab68861d664466b69d4f9826e Mon Sep 17 00:00:00 2001 From: Andy Howard Date: Sat, 12 Sep 2026 12:08:43 +0100 Subject: [PATCH] Define code section comment conventions --- AGENTS.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 4556958..9c5aa54 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -26,6 +26,8 @@ For changes to Common public APIs, target frameworks, packages, or shared behavi Match existing C# conventions: tabs, braces on new lines, top-of-file `using` directives, PascalCase public members, and established `Sbm`/`Sacs` prefixes. Tests use descriptive names such as `Test_Application_ControlDatabase`. No repository-wide formatter is configured, so follow nearby code. Target the framework versions declared in project files. Do not upgrade frameworks or NuGet packages unless explicitly requested. +Across all code files that support `//` line comments, use meaningful section comments instead of solid decorative comment lines. Format a section delimiter as `// --- Caption ---`, where the caption describes the code that follows, such as `Data Members`, `Construction`, `Properties`, `Test Support`, or another context-specific description. Reserve `Utilities` for internal methods that provide relatively simple supporting functionality; use a more specific caption for complex or domain-significant behavior. A delimiter may be followed by explanatory comments when useful. Surround the complete comment block with a blank line so it is visually separate from the preceding and following code; omit only the outside blank line that would otherwise appear directly after an opening brace or directly before a closing brace. Finish the file's main outer class or type block with `// --- The End ---` immediately before its closing brace. Leave nested or internal classes/types comment-free unless the type is complex enough to warrant sections and is at least 32 lines long; `// --- The End ---` is not required for such nested types. Do not add other delimiters where they do not clarify a distinct section. Apply this convention to new files. When an existing file receives significant modification, bring its section comments into line throughout that file as part of the same edit; small, isolated changes do not require unrelated wholesale reformatting. + Processes derived from `SaProcess_Base` must actively poll `IsInterrupted` during long-running loops and before expensive or blocking stages, then exit promptly when cancellation is requested. Use Windows CRLF line endings for C# source, Visual Studio project files, configuration files, PowerShell or command scripts, and general documentation. Use LF for web assets and files commonly consumed by Unix tooling, including SVG, HTML, CSS, JavaScript, shell scripts, and YAML. Follow `.gitattributes` as the authoritative policy. Whenever a file is created or edited, normalize that file to its required line ending as part of the edit, before validation and handoff; do not defer normalization as a separate cleanup step.