Copilot instructions

1---
2description: VS Code coding guidelines — naming, style, types, strings, and code quality rules. Reference when writing or reviewing code.
3applyTo: src/vs/**
4---
5 
6# Coding Guidelines
7 
8Canonical reference: https://github.com/microsoft/vscode/wiki/Coding-Guidelines
9 
10Also see the [Source Code Organization](https://github.com/microsoft/vscode/wiki/Source-Code-Organization) wiki page.
11 
12## Indentation
13 
14Use tabs, not spaces.
15 
16## Naming
17 
18- PascalCase for types and enum values
19- camelCase for functions, methods, properties, and local variables
20- Use whole words when possible
21 
22## Types
23 
24- Do not export types or functions unless shared across multiple components
25- Do not introduce new types or values to the global namespace
26 
27## Comments
28 
29- Use JSDoc style comments for functions, interfaces, enums, and classes
30- Do not write large comments in the middle of a method or comments that explain a single line. If a line or block needs a paragraph of explanation to be understood, treat that as a signal that the code itself is unclear: extract a well-named function, introduce an explanatory variable, or simplify the logic instead. Keep any remaining inline comment to a brief note.
31- **Default to NO comment.** Add one only when the code cannot be made self-explanatory by naming. Code that is obvious from its identifiers must not be commented.
32- **Hard limits** (treat as rules, not suggestions):
33  - JSDoc on a function/interface/property: at most 1–2 short sentences. Do not enumerate every branch/feature, restate the signature, list what it does NOT do, or explain parameters that are obvious from their names/types.
34  - Inline comment inside a method body: at most 1 line, and only for a genuine workaround/hack, a non-obvious ordering constraint, or a surprising side effect. Never narrate the next statement (e.g. `// Expand the variable`, `// loop over args`).
35- Before writing any comment longer than one line, stop and either delete it or shorten it to a single line. A multi-line block comment inside a method body is almost always wrong.
36 
37## Strings
38 
39- `"double quotes"` for user-visible strings that need localization
40- `'single quotes'` for everything else
41- All user-visible strings must be externalized via `nls.localize()` — no string concatenation, use `{0}` placeholders
42 
43## UI Labels
44 
45- Title case for command labels, buttons, and menu items (each major word capitalized)
46- Don't capitalize prepositions of four or fewer letters unless first or last word
47- Sentence case for view titles/headings (only first word capitalized), no trailing period
48 
49## Style
50 
51- Arrow functions over anonymous function expressions
52- Only parenthesize arrow parameters when necessary: `x => x + x` not `(x) => x + x`
53- Always surround loop and conditional bodies with curly braces
54- Open curly braces on the same line
55- No surrounding whitespace in parenthesized constructs
56- Prefer `export function x(…) {…}` over `export const x = (…) => {…}` at top-level scope (better stack traces)
57 
58## Code Quality
59 
60- Include Microsoft copyright header in all files
61- Prefer `async`/`await` over `Promise.then()`
62- Localize all user-facing messages
63- Prefer named regex capture groups over numbered ones
64- Do not use `any` or `unknown` unless absolutely necessary
65- Register disposables immediately after creation — use `DisposableStore`, `MutableDisposable`, or `this._register()`
66- Declare service dependencies in constructors via DI — never access services through `IInstantiationService` elsewhere. In particular, do **not** lazily resolve a service with `this.instantiationService.invokeFunction(accessor => accessor.get(ISomeService))`; add `@ISomeService` as a constructor parameter instead. If a constructor cycle prevents direct injection, break the cycle (e.g. pass the dependency into an `init()`/wiring method from the orchestrator, or relocate the call) rather than reaching through `invokeFunction`/`accessor.get`.
67- Use `IEditorService` to open editors, not `IEditorGroupsService.activeGroup.openEditor`
68- Avoid `bind()`/`call()`/`apply()` solely for `this` — prefer arrow functions
69- Avoid events for control flow between components — prefer direct method calls
70