3.4 KiB
File Editing Conventions
This document collects shared conventions that apply while editing source and documentation files. Each repository's AGENTS.md keeps a short, actionable summary; this file holds the full rules. Repository-specific instructions and .gitattributes remain authoritative for their own scope.
Code Section Comments
For code files that support // comments, use meaningful section delimiters in the form // --- Caption ---, where the caption describes the code that follows. Examples include Data Members, Construction, Properties, Test Support, and Definitions for declarations. Reserve Utilities for relatively simple internal helpers; use a more specific caption for complex or domain-significant behavior. A delimiter may have explanatory comments when useful.
Separate the complete comment block from surrounding code with blank lines, except directly inside opening or closing braces. Finish the file's main outer class or type with // --- The End --- immediately before its closing brace. Leave nested or internal types comment-free unless they are complex and at least 32 lines long; // --- The End --- is not required for nested types.
Apply this convention to new files. When an existing file receives significant modification, bring its section comments into line throughout that file. Small, isolated changes do not require unrelated wholesale reformatting, and section delimiters should only mark distinct sections that improve readability.
Markdown Tables
Every new Markdown document that contains a table must include this document-level style near the top so table headers and cells align to the top:
<style>
table th,
table td {
vertical-align: top;
}
</style>
Preserve the style in existing Markdown documents that contain tables. Add it when a substantive edit introduces a table into a document that does not already have it.
Formatting and Import Cleanup
Follow the repository's .editorconfig, solution settings, and established Visual Studio conventions where available. Use Visual Studio's formatter or the repository's approved equivalent on the changed selection or file when practical. Avoid broad formatting changes to unrelated code, and do not reformat generated, vendored, minified, or otherwise excluded files.
Remove using directives, imports, includes, or equivalent declarations only when they are demonstrably unnecessary. Consider language and build semantics: imports can run module initialization, load CSS or polyfills, register components, provide extension methods, or affect generated or conditional code. In JavaScript and React, preserve intentional bare side-effect imports such as CSS, polyfills, and setup modules. If an import exists only for tests, put it in test code rather than leaving a production placeholder for hypothetical future use. Keep a non-obvious intentional import only with a short comment or other clear explanation.
After cleanup, use the applicable formatter or analyzer to confirm the result where practical, and run the validation required by the affected repository and change.
Line Endings
Follow the repository's .gitattributes as the authority for working-tree line endings. For file types without an explicit ending policy, preserve the file's existing convention and match nearby files; do not introduce mixed endings or normalize unrelated files. Whenever a file is created or edited, ensure that file has its required line endings before validation and handoff.