Code Quality — Standards & Review

CRITICAL SKILL — Be concise, direct, and solution-focused.

---

Core Principles

Principle	Rule
SRP	Single Responsibility — each function/class does ONE thing
DRY	Don't Repeat Yourself — extract duplicates, reuse
KISS	Keep It Simple — simplest solution that works
YAGNI	You Aren't Gonna Need It — don't build unused features
Boy Scout	Leave code cleaner than you found it

---

Naming Rules

Element	Convention
Variables	Reveal intent: userCount not n
Functions	Verb + noun: getUserById() not user()
Booleans	Question form: isActive, hasPermission, canEdit
Constants	SCREAMING_SNAKE: MAX_RETRY_COUNT

Rule: If you need a comment to explain a name, rename it.

---

Function Rules

Rule	Description
Small	Max 20 lines, ideally 5-10
One Thing	Does one thing, does it well
One Level	One level of abstraction per function
Few Args	Max 3 arguments, prefer 0-2
No Side Effects	Don't mutate inputs unexpectedly

---

Code Structure

Pattern	Apply
Guard Clauses	Early returns for edge cases
Flat > Nested	Avoid deep nesting (max 2 levels)
Composition	Small functions composed together
Colocation	Keep related code close

---

Code Review Checklist

Correctness

• Code does what it's supposed to do
• Edge cases handled
• Error handling in place
• No obvious bugs

Security

• Input validated and sanitized
• No SQL/NoSQL injection vulnerabilities
• No XSS or CSRF vulnerabilities
• No hardcoded secrets or sensitive credentials
• AI-Specific: Protection against Prompt Injection (if applicable)
• AI-Specific: Outputs are sanitized before being used in critical sinks

Performance

• No N+1 queries
• No unnecessary loops
• Appropriate caching
• Bundle size impact considered

Testing

• Unit tests for new code
• Edge cases tested
• Tests readable and maintainable

Documentation

• Complex logic commented
• Public APIs documented
• README updated if needed

---

AI & LLM Review Patterns (2025)

Logic & Hallucinations

• Chain of Thought: Does the logic follow a verifiable path?
• Edge Cases: Did the AI account for empty states, timeouts, and partial failures?
• External State: Is the code making safe assumptions about file systems or networks?

Prompt Engineering Review

// ❌ Vague prompt in code
const response = await ai.generate(userInput);

// ✅ Structured & Safe prompt
const response = await ai.generate({
  system: "You are a specialized parser...",
  input: sanitize(userInput),
  schema: ResponseSchema
});

---

Anti-Patterns

❌ Pattern	✅ Fix
Comment every line	Delete obvious comments
Helper for one-liner	Inline the code
Factory for 2 objects	Direct instantiation
utils.ts with 1 function	Put code where used
"First we import..."	Just write code
Deep nesting	Guard clauses
Magic numbers	Named constants
God functions	Split by responsibility
any type	Proper types
Long functions (100+ lines)	Small, focused functions

---

Review Comments Guide

// Blocking issues use 🔴
🔴 BLOCKING: SQL injection vulnerability here

// Important suggestions use 🟡
🟡 SUGGESTION: Consider using useMemo for performance

// Minor nits use 🟢
🟢 NIT: Prefer const over let for immutable variable

// Questions use ❓
❓ QUESTION: What happens if user is null here?

---

AI Coding Style

Situation	Action
User asks for feature	Write it directly
User reports bug	Fix it, don't explain
No clear requirement	Ask, don't assume

---

🔴 Before Editing ANY File (THINK FIRST!)

Question	Why
What imports this file?	They might break
What does this file import?	Interface changes
What tests cover this?	Tests might fail
Is this a shared component?	Multiple places affected

🔴 Rule: Edit the file + all dependent files in the SAME task. 🔴 Never leave broken imports or missing updates.

---

🔴 Self-Check Before Completing (MANDATORY)

Check	Question
✅ Goal met?	Did I do exactly what user asked?
✅ Files edited?	Did I modify all necessary files?
✅ Code works?	Did I test/verify the change?
✅ No errors?	Lint and TypeScript pass?
✅ Nothing forgotten?	Any edge cases missed?

🔴 Rule: If ANY check fails, fix it before completing.

---

Summary

Do	Don't
Write code directly	Write tutorials
Let code self-document	Add obvious comments
Fix bugs immediately	Explain the fix first
Inline small things	Create unnecessary files
Name things clearly	Use abbreviations
Keep functions small	Write 100+ line functions

Remember: The user wants working code, not a programming lesson.