154 lines
4.0 KiB
Markdown
154 lines
4.0 KiB
Markdown
# Best Practices
|
|
|
|
Generate code that is **simple**, **understandable**, **reviewable**, **scalable**, **optimized**, and **modern**. Follow W3C web standards and platform conventions.
|
|
|
|
## Naming Conventions
|
|
|
|
### Files
|
|
|
|
| Type | Convention | Example |
|
|
| ---------- | --------------------------- | -------------------- |
|
|
| Components | PascalCase | `WorkshopZone.tsx` |
|
|
| Hooks | camelCase with `use` prefix | `useGameState.ts` |
|
|
| Managers | PascalCase | `GameManager.ts` |
|
|
| Utils | PascalCase | `Dispose.ts` |
|
|
| Data | PascalCase | `missions.ts` |
|
|
| Shaders | kebab-case | `hologram.vert.glsl` |
|
|
|
|
### Variables & Functions
|
|
|
|
| Type | Convention | Example |
|
|
| ---------------- | -------------------- | ----------------------------------------- |
|
|
| Variables | camelCase | `activeZone`, `missionStep` |
|
|
| Functions | camelCase | `startMission()`, `setActiveZone()` |
|
|
| Constants | UPPER_SNAKE_CASE | `MAX_SPEED`, `DEFAULT_PHASE` |
|
|
| React components | PascalCase | `function WorkshopZone()` |
|
|
| React hooks | camelCase with `use` | `useGameState()`, `useFrame()` |
|
|
| Classes | PascalCase | `class GameManager` |
|
|
| Interfaces/Types | PascalCase | `type GameSnapshot`, `interface ZoneData` |
|
|
|
|
## Code Style
|
|
|
|
### Simplicity First
|
|
|
|
```ts
|
|
// Good — clear, direct
|
|
function getZoneRadius(zone: Zone): number {
|
|
return zone.radius;
|
|
}
|
|
|
|
// Bad — over-abstracted
|
|
function getZoneRadius(zone: Zone): number {
|
|
return zone[ZoneFields.RADIUS] ?? RADIUS_DEFAULTS[zone.type]?.default ?? 50;
|
|
}
|
|
```
|
|
|
|
### Early Return
|
|
|
|
```ts
|
|
// Good
|
|
if (!gltf) return null;
|
|
if (!visible) return null;
|
|
|
|
return <primitive object={gltf.scene} />;
|
|
```
|
|
|
|
### Avoid Nested Callbacks
|
|
|
|
```ts
|
|
// Good — flat structure
|
|
useEffect(() => {
|
|
const mixer = new THREE.AnimationMixer(model);
|
|
|
|
return () => mixer.stopAllAction();
|
|
}, [model]);
|
|
```
|
|
|
|
## TypeScript Rules
|
|
|
|
### Explicit Types for Exports
|
|
|
|
```ts
|
|
export function useGameState(): GameSnapshot { ... }
|
|
|
|
export function setPhase(phase: Phase): void { ... }
|
|
```
|
|
|
|
### Never use `any`
|
|
|
|
```ts
|
|
// Good
|
|
const ref = useRef<THREE.Group>(null);
|
|
|
|
// Bad
|
|
const ref = useRef<any>(null);
|
|
```
|
|
|
|
## Performance
|
|
|
|
### useRef for Mutable Values
|
|
|
|
```ts
|
|
// Good — no re-render
|
|
const position = useRef(new THREE.Vector3());
|
|
|
|
// Bad — triggers re-render every frame
|
|
const [position, setPosition] = useState(new THREE.Vector3());
|
|
```
|
|
|
|
### Memoize Expensive Computations
|
|
|
|
```ts
|
|
const memoizedValue = useMemo(() => computeExpensiveValue(a, b), [a, b]);
|
|
```
|
|
|
|
## Scalability
|
|
|
|
### Single Responsibility
|
|
|
|
```ts
|
|
// Good — focused component
|
|
export function WorkshopZone() {
|
|
// Only handles workshop zone logic
|
|
}
|
|
|
|
// Bad — does everything
|
|
export function WorkshopZone() {
|
|
// Handles zone logic + audio + cinematics + missions
|
|
}
|
|
```
|
|
|
|
### Constants for Magic Numbers
|
|
|
|
```ts
|
|
const DEFAULT_CAMERA_DISTANCE = 5;
|
|
const ZONE_DETECTION_RADIUS = 20;
|
|
```
|
|
|
|
## Accessibility (W3C)
|
|
|
|
### Semantic HTML
|
|
|
|
```tsx
|
|
// Good
|
|
<button onClick={handleInteract} aria-label="Interact with bike">
|
|
<Model />
|
|
</button>
|
|
|
|
// Bad
|
|
<div onClick={handleInteract}>
|
|
<Model />
|
|
</div>
|
|
```
|
|
|
|
## Rules
|
|
|
|
1. **Simplicity** — Every line of code must be justified.
|
|
2. **Readability** — Code is read 10x more than it's written.
|
|
3. **Reviewability** — PRs should be understandable in < 5 minutes.
|
|
4. **Scalability** — Architecture should support growth without refactoring.
|
|
5. **Performance** — Don't optimize prematurely, but don't introduce obvious bottlenecks.
|
|
6. **Modern** — Use ES2022+ features, TypeScript strict mode, React hooks.
|
|
7. **W3C** — Follow web standards: semantic HTML, ARIA, keyboard navigation.
|
|
8. **No Over-Engineering** — Avoid patterns that add complexity without benefit.
|