@wuchuheng/setup
Version:
CLI tool to initialize project with common configuration files
196 lines (139 loc) • 6.33 kB
Markdown
# GitHub Copilot Project Rules (Multi‑language)
Purpose: Provide clear, enforceable guidance so AI‑generated code matches our commenting and readability standards.
Scope: Applies to all source files in this repository. Language adapters below specify how to express the same standards.
## TL;DR (defaults Copilot must follow)
- Add doc comments for classes/types, properties/fields, and functions/methods.
- Use numbered inline comments only inside function/method bodies to mark steps.
- Always follow 1/2/3 phases: 1 = Input, 2 = Core, 3 = Output; omit for trivial bodies.
- Never place numbered comments at file/module scope, on decorators/annotations, or above properties.
- Keep lines ≤ 120 chars; wrap args, template strings, and objects for readability.
- Match nearby file style; prefer explicit types and safe narrowing when applicable.
## Defaults checklist (for Copilot)
- JSDoc/Javadoc/docstring present on: classes/types, fields, and functions/methods (concise and relevant).
- Numeric comments only inside function bodies for non‑trivial logic (1/2/3; use 1.1, 2.2.1 when it helps).
- ≤ 120 chars per line; break long args/objects/strings across lines with trailing commas where supported.
- No implicit any where typing exists; add minimal explicit types or guards.
- Comments are short, actionable, and near the code they describe.
## Three‑phase numeric comment convention (all languages)
Use numeric comments only inside function/method bodies.
- 1.\* Input Handling: validate/parse parameters, type checks, defaults, guards.
- 2.\* Core Processing: transformations, calculations, I/O, side effects.
- 3.\* Output Handling: return values, emit/resolve/respond, cleanup.
Minimal example:
```ts
const formatHour = (hour: number): string => {
// 3. Output handling
return `${hour}:00`;
};
```
Non‑trivial example (language‑agnostic structure):
```pseudo
function handle(data) {
// 1. Input handling
// 1.1 Validate shape; 1.2 Apply defaults
// 2. Core processing
// 2.1 Transform; 2.2 Persist
// 3. Output handling
// 3.1 Return result
}
```
## Documentation placement rules (generic)
- File/module: No numeric comments. Optional brief header comment if needed.
- Class/Type/Struct/Interface/Enum: Doc comment above declaration; describe purpose and constraints.
- Property/Field: Doc comment above; describe purpose, type/units, constraints.
- Function/Method: Doc comment above; describe purpose, params, return value, notable side effects.
Never use numeric comments outside a function/method body.
## Language adapters (how to write doc comments)
- TypeScript/JavaScript/TSX/JSX: JSDoc with `/** ... */`; use `@param`, `@returns` when helpful.
- Python: Triple‑quoted docstrings under defs/classes; Google/NumPy style is fine; inline `# 1.` comments in bodies.
- Go: Line doc starting with the name, e.g., `// Foo does ...`; inline `// 1.` inside functions only.
- Java/Kotlin: Javadoc/KDoc `/** ... */` with `@param`, `@return`; inline `// 1.` inside methods only.
- C#/C++: C# XML doc `/// <summary>...`; C++ Doxygen `///` or `/** ... */`; numeric `// 1.` only inside bodies.
- Rust: `///` item docs; `//` inside functions for numeric comments.
- Shell (bash/sh/pwsh): `#` header above functions; numeric `# 1.` within functions only.
If a language has a project formatter configured, adhere to it.
## React/TSX specifics (when applicable)
- Components: Doc above component describing purpose and props; doc each prop in its type/interface.
- Hooks: Doc inputs/outputs and side effects. In useEffect/useMemo, add numeric comments only for multi‑step logic.
Example:
```tsx
/** Renders a labeled time display. */
type TimeProps = {
/** Hour in 0–23. */
hour: number;
};
export function TimeLabel({ hour }: TimeProps) {
// 3. Output handling
return <span>{`${hour}:00`}</span>;
}
```
## Async, IPC/HTTP, and error handling (all stacks)
- Always structure handlers as 1 (validate/parse), 2 (do work: DB/HTTP/IPC/FS), 3 (return/respond/cleanup).
- Node/Electron example:
```ts
ipcMain.handle("log:add", async (_e, payload) => {
// 1. Input handling
if (!payload || typeof payload.message !== "string")
throw new Error("Invalid payload");
// 2. Core processing
const id = await logService.create(payload);
// 3. Output handling
return { id };
});
```
- Python (Flask) example:
```py
@app.post('/log/add')
def add_log():
# 1. Input handling
body = request.get_json(silent=True) or {}
msg = body.get('message')
if not isinstance(msg, str): abort(400, 'Invalid payload')
# 2. Core processing
_id = service_create(body)
# 3. Output handling
return { 'id': _id }, 201
```
## Do / Don’t
Do
- Add doc comments to declarations; use numeric comments only inside bodies.
- Keep lines ≤ 120 chars; wrap long args/objects/strings.
- Prefer clarity and consistency; align to nearby style.
Don’t
- Don’t add numbered comments at module scope, on decorators/annotations, or above properties.
- Don’t overuse sub‑numbering; nest only when it improves clarity.
Incorrect (avoid):
```ts
// 1. Primary identification
@PrimaryGeneratedColumn('uuid')
id: string;
```
## Readability constraints (≤ 120 chars per line)
If a line would exceed 120 chars, refactor:
- Break argument lists across lines with trailing commas (where supported).
- Split template literals / long strings or extract variables.
- Spread object/record/map literals across multiple lines with aligned keys.
- Extract intermediate variables to clarify complex expressions.
## Consistency, conflict, and precedence
- Match existing repository style first; otherwise follow these rules.
- Apply rules across all code (Electron main, renderer, scripts, services).
- Prefer omitting numeric comments for trivial getters/setters.
## Tooling
- JS/TS/TSX: Prettier enforces print width 120 (see `.prettierrc.json`).
- Python: Use black/isort if configured.
- Go: gofmt/goimports.
- Rust: rustfmt.
- Java/Kotlin: formatter/ktlint if configured.
- C#/C++: dotnet/clang‑format if configured.
Keep code formatted consistently with project tools.