# Clean Code

> Enforces clean code standards across NestJS, React, and Next.js: minimal scope, no over-engineering, match existing conventions, focused functions, proper error handling. Use when writing, reviewing, or refactoring code in any stack.

- Skill: `xmuhameed/clean-code` (Agent Skill)
- Install (CLI): `npx skillmds@latest add xmuhameed/clean-code`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xmuhameed/clean-code/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: xmuhameed (https://skillmd.com/u/xmuhameed)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/xmuhameed/clean-code

---


# Clean Code

Apply to every change. Read surrounding code first — match the author's style.

## Core Rules

1. **Minimal scope** — only change what the task requires
2. **No over-engineering** — no abstractions for one-time use; three similar lines > premature helper
3. **Match conventions** — naming, imports, error handling, response format, formatting
4. **Self-explanatory code** — comments only for non-obvious business logic
5. **Meaningful names** — `activeCategories` not `data`; `handleDeleteCategory` not `handleClick`

## Backend (NestJS)

- Controllers thin — delegate to service, use response helpers
- Services: `try/catch` → `handleException`; business errors → `CustomHttpException`
- DTOs: global field decorators; barrel `dto/index.ts`
- Prisma: build `where` incrementally; `Promise.all` for count + findMany

## Frontend (React / Next.js)

- Server Components for fetch; Client for interactivity only
- Server state → React Query; global client → Zustand; URL → `useSearchParams`
- API in feature `api/` folder; query key factories
- Forms: Zod + RHF; files in separate `useState`

## Error Handling

| Layer | Pattern |
|-------|---------|
| Backend service | `handleException(error, false, {})` |
| Backend business | `CustomHttpException(message, status)` |
| Frontend API | 401 interceptor; mutation `onError` → toast |
| Forms | `showFormValidationToast` |

## Never

- Placeholder/lorem data in production code
- Empty `catch {}` blocks
- Business logic in controllers or JSX
- God files (600-line routers, 500-line services)
- Unrelated file changes
- `any` unless unavoidable (file fields, JSON settings)

## Review Checklist

- [ ] Smallest diff that solves the problem
- [ ] Matches surrounding patterns
- [ ] Error cases handled
- [ ] No dead code / unused imports
- [ ] Bilingual fields paired (`_en`/`_ar`) if localized entity

Refactor only when asked or required by the task — not proactively.