|
1 | 1 | # Mila — Copilot Instructions |
2 | 2 |
|
3 | | -## Code generation policy |
| 3 | +## General Guidelines |
4 | 4 | - Generate code only when explicitly requested (e.g., "implement", "update", "write code", "generate", "create code"). Otherwise provide analysis, design guidance, and minimal examples. |
5 | | -- Mila is at the Alpha stage of development, please do not consider backward compatibility with previous versions when generating code. |
| 5 | +- Mila is at the Alpha stage of development; please do not consider backward compatibility with previous versions when generating code. |
6 | 6 |
|
7 | | -## Doxygen / file header policy |
8 | | -- File-level Doxygen comments must be concise summaries (one to three short sentences). |
9 | | - - Purpose: provide a quick summary of the file intent for readers and tools. |
10 | | - - Must NOT repeat detailed API, implementation notes, or usage examples. |
11 | | -- Detailed documentation belongs in the module/class/function-level Doxygen comments (module API). |
12 | | - - Put behavior, parameters, return semantics, ownership/lifetime, threading assumptions, and examples on the relevant symbol's Doxygen block. |
13 | | - - Module-level comments (module partitions) should describe the public API surface and usage patterns. |
14 | | -- Example file-level header (preferred): |
15 | | - - Brief one-line summary: "Configuration for the Residual module." |
16 | | - - Optional short second sentence for scope: "Provides fluent setters used by Residual and backend factories." |
17 | | -- Rationale: keeps files scannable and avoids duplicated, stale documentation across many files. |
18 | | - |
19 | | -## Coding Style |
20 | | - |
21 | | -### Blank Lines Around Blocks |
22 | | -- Add blank line before control flow blocks (if, for, while, switch) |
23 | | -- Add blank line after closing brace of blocks |
24 | | -- Exception: No blank line between `} else {` or `} catch {` |
25 | | - |
26 | | -### Blank Lines Around Return Statements |
27 | | -- Add blank line before `return` statement (final return in function) |
28 | | -- Exception: Early returns (guard clauses) don't need blank line |
29 | | -- Exception: Single-statement functions don't need blank line |
| 7 | +## Code Style |
| 8 | +- Do not columnize/align code with extra spaces. Identifiers and types should use standard single-space formatting. Column alignment breaks when names change. |
| 9 | +- Add blank line before control flow blocks (if, for, while, switch). |
| 10 | +- Add blank line after closing brace of blocks. |
| 11 | +- Exception: No blank line between `} else {` or `} catch {`. |
| 12 | +- Add blank line before `return` statement (final return in function). |
| 13 | +- Exception: Early returns (guard clauses) don't need blank line. |
| 14 | +- Exception: Single-statement functions don't need blank line. |
30 | 15 |
|
31 | 16 | ## High-level constraints |
32 | 17 | - Project is alpha: breaking changes and simplifications are acceptable. |
33 | 18 | - Backward compatibility is NOT required. Do not use Deprecated APIs. |
34 | | -- Do not use Mila deprecated API |
| 19 | +- Do not use Mila deprecated API. |
35 | 20 | - Host code: C++23 using modules and module partitions. Tests: GTest. Build: CMake + Ninja. |
36 | 21 |
|
37 | | -## Comment policy |
| 22 | +## Comment Policy |
38 | 23 | - NEVER generate trivial comments that simply restate what the code does. For example, do not generate comments like: |
39 | 24 | - `// increment i` for the line `i++;` |
40 | 25 | Such trivial, repetitive comments must not be produced by Copilot. |
41 | | -- Use only ASCII characters (no Unicode checkmarks, emojis, or special symbols) |
42 | | -- Don't add simple validation comments (e.g., "Good", "Correct", "OK", "Bad") |
43 | | -- Comments should explain WHAT the code's intent or contract is, or WHY a non-obvious approach is required — not restate HOW the code performs obvious operations. |
44 | | - - Good: `// accumulate running mean across batch to avoid a second pass` |
45 | | - - Good: `// Use integer index to preserve pointer stability required by the SIMD kernel` |
| 26 | +- Use only ASCII characters (no Unicode checkmarks, emojis, or special symbols). |
| 27 | +- Don't add simple validation comments (e.g., "Good", "Correct", "OK", "Bad"). |
| 28 | +- Comments should explain WHAT the code's intent or contract is, or WHY a non-obvious approach is required—not restate HOW the code performs obvious operations. |
| 29 | + - Good: `// accumulate running mean across batch to avoid a second pass`. |
| 30 | + - Good: `// Use integer index to preserve pointer stability required by the SIMD kernel`. |
46 | 31 | - Prefer documenting: |
47 | 32 | - Function/module contract: inputs, outputs, side-effects, threading assumptions, and performance/precision trade-offs. |
48 | 33 | - Non-obvious algorithms, invariants, and corner cases that callers or maintainers must preserve. |
49 | 34 | - API expectations: ownership, lifetime, and accumulation semantics (overwrite vs accumulate). |
50 | 35 | - Keep comments technical and informative, not evaluative or apologetic. |
51 | 36 | - Do not include reasoning or justification for design decisions in code comments (keep rationale in design documents or commit messages). |
52 | 37 | - Avoid commenting trivial lines of code that are self-explanatory; prefer a brief block comment describing the overall purpose of the surrounding code instead. |
53 | | -- Documentation comments (Doxygen) should describe behavior, usage, public contracts and examples — not explain why changes were made. |
| 38 | +- Documentation comments (Doxygen) should describe behavior, usage, public contracts, and examples—not explain why changes were made. |
| 39 | + |
| 40 | +## Doxygen / File Header Policy |
| 41 | +- File-level Doxygen comments must be concise summaries (one to three short sentences). |
| 42 | + - Purpose: provide a quick summary of the file intent for readers and tools. |
| 43 | + - Must NOT repeat detailed API, implementation notes, or usage examples. |
| 44 | +- Detailed documentation belongs in the module/class/function-level Doxygen comments (module API). |
| 45 | + - Put behavior, parameters, return semantics, ownership/lifetime, threading assumptions, and examples on the relevant symbol's Doxygen block. |
| 46 | + - Module-level comments (module partitions) should describe the public API surface and usage patterns. |
| 47 | +- Example file-level header (preferred): |
| 48 | + - Brief one-line summary: "Configuration for the Residual module." |
| 49 | + - Optional short second sentence for scope: "Provides fluent setters used by Residual and backend factories." |
| 50 | +- Rationale: keeps files scannable and avoids duplicated, stale documentation across many files. |
54 | 51 |
|
55 | | -## Doxygen guidance for generated code |
| 52 | +## Doxygen Guidance for Generated Code |
56 | 53 | - When emitting Doxygen for symbols: |
57 | 54 | - Use the full signature and describe preconditions, postconditions, and side-effects. |
58 | 55 | - Prefer param/return tags for public methods. |
59 | 56 | - Use short examples only in the symbol comment (not in file headers). |
60 | 57 | - Avoid emitting long prose in file headers; put detail in the API-level documentation. |
61 | 58 |
|
62 | | -## Notes for AI assistant |
| 59 | +## Notes for AI Assistant |
63 | 60 | - When recommending code, prefer modern C++ idioms (RAII, smart pointers, STL algorithms). |
64 | 61 | - Always include testing suggestions and consider CPU/CUDA parity. |
65 | | -- In explanatory text (not code), you may use formatting symbols for clarity, but generated code comments must follow the comment policy above |
66 | | -- Keep commit messages and explanatory responses separate from code documentation |
67 | | -- Unit tests are structured by project, namespace and class — place tests under the Tests tree following the repository project layout and mirror the production namespace/class organization. |
| 62 | +- In explanatory text (not code), you may use formatting symbols for clarity, but generated code comments must follow the comment policy above. |
| 63 | +- Keep commit messages and explanatory responses separate from code documentation. |
| 64 | +- Unit tests are structured by project, namespace, and class—place tests under the Tests tree following the repository project layout and mirror the production namespace/class organization. |
0 commit comments