Common Pitfalls & Solutions
Real-world mistakes developers make and how to fix them - learn from others' experiences
Common Pitfalls & Solutions
Overview
This guide documents the most common mistakes developers make in our codebase and provides clear solutions. Each pitfall includes real examples from code reviews, why it's problematic, and the correct approach.
For Junior Developers: These are mistakes we've all made. Learning from them will accelerate your growth.
For AI Assistants: Avoid these patterns and apply the solutions when generating code.
Navigation & Architecture Pitfalls
Pitfall 1: Creating Duplicate Business Logic
The Problem: Implementing the same business logic in multiple places instead of using existing domains.
Pitfall 2: Wrong File Placement
The Problem: Putting files in incorrect locations, breaking the project structure.
Pitfall 3: Incorrect Import Paths
The Problem: Using relative imports everywhere or incorrect absolute imports.
State Management Pitfalls
Pitfall 4: State in Wrong Place
The Problem: Putting state at the wrong level or using wrong state type.
Pitfall 5: Direct State Mutations
The Problem: Mutating state directly instead of creating new references.
Component Pitfalls
Pitfall 6: Inline Everything
The Problem: Creating functions, objects, and styles inline in render.
Pitfall 7: Missing Error Boundaries
The Problem: Not handling component errors, causing white screens.
API & Async Pitfalls
Pitfall 8: Manual API State Management
The Problem: Managing loading, error, and data states manually instead of using React Query.
Pitfall 9: Race Conditions
The Problem: Not handling async operations properly, causing race conditions.
TypeScript Pitfalls
Pitfall 10: Type System Misuse
The Problem: Using any, missing types, or wrong type patterns.
Performance Pitfalls
Pitfall 11: Unnecessary Re-renders
The Problem: Components re-rendering more than necessary.
Quick Reference Card
Before Writing Code, Ask:
-
Does this logic already exist?
- Check domains first
- Search for similar patterns
- Reuse instead of rewrite
-
Where should this code go?
- Use the Feature Implementation Decision Tree
- Follow the 3+ rule
- Check project structure
-
Is this the right state type?
- Server state → React Query
- Global state → Zustand
- Local state → useState
- Form state → React Hook Form
-
Am I following the patterns?
- Check TypeScript & React Patterns
- Follow naming conventions
- Use proper types
-
Have I handled errors?
- Add error boundaries
- Handle null/undefined
- Provide user feedback
For Team Leads
Code Review Checklist
When reviewing PRs, check for these common issues:
- Code is in the correct location
- No duplicate business logic
- Proper TypeScript types (no
any) - Error handling is present
- Performance optimizations applied
- Following established patterns
- Tests are included
Onboarding New Developers
- Start with this guide
- Review the Decision Tree together
- Pair program on first features
- Do thorough code reviews
- Encourage questions