Marcos Paulo
49 lines
1.7 KiB
Markdown
49 lines
1.7 KiB
Markdown
# Rule: code style
|
|
|
|
## Match what is there
|
|
|
|
This codebase has a real voice: dense one-liner CSS, terse ES modules, comments
|
|
that explain _why_ and never _what_. Do not reformat it into someone else's
|
|
house style as a side effect of a task.
|
|
|
|
The one exception is CSS minification-by-hand — `styles.css` is single-line and
|
|
unreadable. Component `<style>` blocks should be normally formatted. That is an
|
|
improvement, not a style disagreement.
|
|
|
|
## Comments
|
|
|
|
Write the comment that stops the next person from making a mistake. The existing
|
|
codebase does this well:
|
|
|
|
```js
|
|
// The cluster's nginx ingress runs with `use-forwarded-headers` off, so it
|
|
// *overwrites* X-Forwarded-For with its own downstream peer — the VPS's
|
|
// tailnet address — which would collapse every visitor into a single voter.
|
|
```
|
|
|
|
That comment earns its place. `// set the colour` does not.
|
|
|
|
## Naming
|
|
|
|
- Components `PascalCase.astro`; everything else `kebab-case`.
|
|
- Booleans read as assertions: `isOpen`, `hasVoted`, not `open`, `voted`.
|
|
- No abbreviations that are not already in the codebase's vocabulary.
|
|
|
|
## TypeScript
|
|
|
|
Astro brings TS. Use it: typed props, typed collections, `strict` on. Never
|
|
`any` — if the type is genuinely unknown, `unknown` plus a narrow.
|
|
|
|
## Dead code
|
|
|
|
Delete it. Do not comment it out, do not leave it behind a flag. Git remembers.
|
|
|
|
This matters here specifically: `responsive.css` is 30 KB of accumulated
|
|
overrides, and the temptation during migration will be to port it wholesale
|
|
"just in case". Prove each rule is needed or drop it.
|
|
|
|
## Commits
|
|
|
|
Present tense, lowercase, `type: subject`, matching the existing log (`feat:`,
|
|
`fix:`, `docs:`). The body explains why, and states what you did not do.
|