10 Skills Every Development Team Should Have

# Code Style Standards

## Formatting
- Use 2 spaces for indentation (no tabs)
- Maximum line length: 100 characters
- Use trailing commas in multi-line arrays/objects
- Always use semicolons

## Naming
- Variables/functions: camelCase
- Classes/components: PascalCase
- Constants: SCREAMING_SNAKE_CASE
- Files: kebab-case.ts

## Structure
- One component/class per file
- Group imports: external, internal, relative
- Export at the bottom of the file

# TypeScript Standards

## Type Safety
- Enable strict mode in tsconfig
- Never use `any` - use `unknown` if type is truly unknown
- Prefer interfaces for object shapes, types for unions/primitives
- Always define explicit return types on exported functions

## Patterns
- Use discriminated unions for state management
- Prefer const assertions for literal types
- Use generics to avoid code duplication
- Leverage utility types (Pick, Omit, Partial, Required)

## Avoid
- Type assertions (as) unless absolutely necessary
- Non-null assertions (!) - handle null cases explicitly
- Enums - use const objects or union types instead

# React Patterns

## Component Structure
- Use functional components with hooks
- Define prop interface above the component
- Use named exports (not default exports)
- Order: types → component → styles → exports

## Hooks
- Extract complex logic into custom hooks
- Follow the Rules of Hooks strictly
- Use useMemo/useCallback for expensive operations
- Prefer useReducer for complex state

## Props
- Destructure props in function signature
- Provide default values where sensible
- Use children prop for composition
- Avoid prop drilling - use context for deep data

## State Management
- Keep state as local as possible
- Lift state only when necessary
- Use context for truly global state
- Consider state machines for complex flows

# API Design Standards

## Endpoint Structure
- Use RESTful conventions: GET, POST, PUT, DELETE
- Resource naming: plural nouns (/users, /orders)
- Nested resources: /users/:id/orders
- Use query params for filtering/pagination

## Request/Response
- Always validate input with Zod or similar
- Return consistent response shapes
- Include appropriate HTTP status codes
- Provide meaningful error messages

## Error Handling
- 400: Bad request (validation errors)
- 401: Unauthorized (not authenticated)
- 403: Forbidden (not authorized)
- 404: Not found
- 500: Server error (log details, return generic message)

## Security
- Validate all user input
- Sanitize data before database queries
- Use parameterized queries (never string concatenation)
- Rate limit sensitive endpoints

# Testing Guidelines

## Structure
- Test files next to source: component.tsx → component.test.tsx
- Use describe blocks to group related tests
- One assertion per test when possible
- Name tests clearly: "should [expected behavior] when [condition]"

## Unit Tests
- Test pure functions and utilities thoroughly
- Mock external dependencies
- Test edge cases and error conditions
- Aim for 80%+ coverage on business logic

## Integration Tests
- Test API endpoints end-to-end
- Use test database, not mocks
- Clean up test data after each test
- Test authentication/authorization flows

## Component Tests
- Test user interactions, not implementation
- Use Testing Library queries (getByRole, getByText)
- Avoid testing internal state
- Test accessibility where relevant

# Error Handling Standards

## Principles
- Never swallow errors silently
- Log errors with context (user, action, timestamp)
- Show user-friendly messages, log technical details
- Use error boundaries for React components

## Backend
- Use custom error classes for different error types
- Include error codes for programmatic handling
- Return appropriate HTTP status codes
- Never expose stack traces in production

## Frontend
- Wrap async operations in try/catch
- Show loading and error states
- Provide retry mechanisms where appropriate
- Report errors to monitoring service

## Patterns
- Use Result types for operations that can fail
- Prefer throwing early over nested conditionals
- Always clean up resources in finally blocks
- Document expected error conditions

# Security Checklist

## Input Validation
- Validate all user input on the server
- Use allowlists, not blocklists
- Sanitize HTML to prevent XSS
- Validate file uploads (type, size, content)

## Authentication
- Use secure password hashing (bcrypt, argon2)
- Implement proper session management
- Use HTTPS everywhere
- Secure cookie settings (HttpOnly, Secure, SameSite)

## Authorization
- Check permissions on every request
- Use principle of least privilege
- Validate ownership before operations
- Log authorization failures

## Data Protection
- Never log sensitive data (passwords, tokens, PII)
- Encrypt sensitive data at rest
- Use parameterized queries (prevent SQL injection)
- Implement rate limiting on sensitive endpoints

## Dependencies
- Keep dependencies updated
- Audit for known vulnerabilities
- Review new dependencies before adding
- Use lockfiles for reproducible builds

# Code Review Checklist

## Before Approving, Verify:

### Correctness
- [ ] Code does what the PR description claims
- [ ] Edge cases are handled
- [ ] Error handling is appropriate
- [ ] No obvious bugs or logic errors

### Quality
- [ ] Code is readable and well-organized
- [ ] Functions are focused and appropriately sized
- [ ] No code duplication
- [ ] Names are clear and meaningful

### Standards
- [ ] Follows team coding standards
- [ ] TypeScript types are appropriate
- [ ] Tests are included and meaningful
- [ ] Documentation updated if needed

### Security
- [ ] Input is validated
- [ ] No sensitive data exposed
- [ ] Authorization checks in place
- [ ] No security anti-patterns

### Performance
- [ ] No obvious performance issues
- [ ] Database queries are efficient
- [ ] No unnecessary re-renders (React)
- [ ] Large operations are async

# Documentation Standards

## When to Document
- Public APIs and exported functions
- Complex business logic
- Non-obvious code decisions
- Workarounds and technical debt

## JSDoc Format
- Include @param for all parameters
- Include @returns for return values
- Add @throws for functions that throw
- Use @example for complex functions

## README Requirements
- Project overview and purpose
- Setup instructions
- Environment variables
- Common commands
- Architecture overview (for complex projects)

## Code Comments
- Explain "why", not "what"
- Keep comments up to date with code
- Remove commented-out code
- Use TODO/FIXME with ticket numbers

# Git Conventions

## Branch Naming
- feature/description-of-feature
- fix/description-of-fix
- chore/description-of-chore
- refactor/description-of-refactor

## Commit Messages
- Use conventional commits: type(scope): description
- Types: feat, fix, docs, style, refactor, test, chore
- Keep subject under 72 characters
- Use imperative mood: "Add feature" not "Added feature"

## Pull Requests
- One feature/fix per PR
- Keep PRs small (<400 lines when possible)
- Include description of changes
- Link to relevant issues/tickets

## Workflow
- Always branch from main
- Rebase before merging (keep history clean)
- Squash commits if history is messy
- Delete branches after merging