code-organization

Code Organization Rules

File Size and Method Placement

Prefer New Files for Large Methods

When adding large methods or substantial functionality, PREFER creating new files over expanding existing files to very large sizes.

Guidelines:

• ✅ Create a new file when adding a method that:

  • Exceeds ~100-150 lines of code
  • Has complex logic with multiple responsibilities
  • Would push an existing file over ~400-500 lines
  • Is a distinct feature or capability that can be logically separated

• ✅ Extract to a new file when an existing file:

  • Exceeds ~500 lines and you're adding more functionality
  • Contains multiple distinct concerns that can be separated
  • Has methods that are rarely used together

• ✅ Keep related functionality together when:

  • Methods are tightly coupled and always used together
  • The file is still under ~400 lines
  • Splitting would create unnecessary indirection

File Organization Patterns

Frontend (TypeScript/React)

Services:

// ✅ CORRECT: Split large service into focused modules
// services/calendar/core/service.ts (main service)
// services/calendar/events/operations.ts (event operations)
// services/calendar/calendars/management.ts (calendar management)

// ❌ AVOID: Single massive service file
// services/calendar/service.ts (1000+ lines with everything)

Hooks:

// ✅ CORRECT: Separate hooks by concern
// hooks/data/useCalendarEvents.ts
// hooks/data/useCalendarPreferences.ts
// hooks/data/useCalendarAvailability.ts

// ❌ AVOID: Single hook file with multiple large hooks
// hooks/data/useCalendar.ts (500+ lines with all calendar hooks)

Components:

// ✅ CORRECT: Extract large components or logic; utilities live in packages
// packages/features/calendar/components/Calendar.tsx (main component)
// packages/features/calendar/components/CalendarView.tsx
// packages/utils/calendar/eventParsing.ts (utilities – not under apps/web)

// ❌ AVOID: Single massive component file
// features/calendar/Calendar.tsx (800+ lines with everything)

// ❌ AVOID: Standalone .ts utilities under apps/web/features or components
// features/calendar/utils/eventParsing.ts