tomevault-io 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.
Converted and distributed by TomeVault — claim your Tome and manage your conversions.