Skip to content

docs(decision-records): add inline comments explaining custom implementations

Greeshma Kanukunta requested to merge docs/decision-records-and-lint-fix into develop

Overview

This MR adds inline decision record comments for custom implementations used in the codebase. It improves maintainability by documenting the rationale behind these decisions, helping future contributors understand trade-offs and avoid redundant rewrites.

What does this MR do and why?

Previously, several parts of the project used custom implementations without documenting why established FOSS libraries were not adopted. This lack of context could lead to confusion, duplication of effort, or incorrect refactoring.

This MR addresses that gap by:

  • Adding inline decision record comments in key files.
  • Explaining the reasoning behind choosing custom implementations.
  • Highlighting trade-offs and future considerations.

The approach uses inline comments instead of separate ADR files to keep documentation close to the code.

Changes Made

Documentation Updates

  • src/contexts/ThemeContext.tsx
  • src/utils/searchUtils.ts
  • src/lib/utils.ts (specifically formatToIST)
  • src/contexts/AuthContext.tsx

Note: No functional code changes were made in this MR.

Technical Details

  • Logic: No logic changes.
  • Content: Only comments added.
  • Specifics covered: * Alternative libraries considered (next-themes, Fuse.js, date-fns-tz).
    • Trade-offs (performance vs. feature set).
    • Future considerations for when to migrate to a library.

Type of Change

  • 📝 Documentation update

How to Set Up and Validate Locally

  1. Checkout the branch: 
    git checkout docs/decision-records-fix
  2. Install dependencies: 
    bun install
  3. Run the development server: 
    bun dev

Verify:

  • App runs normally.
  • No functional changes observed in UI or behavior.
  • Comments are clearly visible in the updated files listed above.

Testing Done

  • Manual testing completed to ensure no syntax errors were introduced in the TSX/TS files.

Test Cases

Scenario Expected Result Status
App loads No change in startup behavior ✅
Navigation Works normally across all routes ✅
Comments Present and correctly formatted in source code ✅

Code Quality Checklist

  • No logic changes
  • No unused code
  • No console logs
  • Lint passes
  • No UI/API changes

Notes

  • This is a documentation-only change.
  • Safe to merge as it does not affect the production bundle logic.
  • Significantly improves long-term maintainability for new developers. """
Edited by Greeshma Kanukunta

Merge request reports