Update cleanup-improve-code-quality.md

Author: conradkoh

guides/routines/cleanup-improve-code-quality.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-This document provides a systematic approach to improving code quality through proper organization, naming conventions, and documentation. This routine should be applied to TypeScript/JavaScript files in React, Next.js, and Convex backend projects.
+This document provides a systematic step-by-step approach to improving code quality for individual TypeScript/JavaScript files in React, Next.js, and Convex backend projects. Follow these steps in order for each file you're cleaning up.
 
 ## Core Principles
 
@@ -11,19 +11,27 @@ This document provides a systematic approach to improving code quality through p
 3. **Clear Boundaries**: Internal vs. external APIs must be obvious
 4. **Self-Documenting**: Functions and interfaces must explain their purpose
 
-## Cleanup Steps
+## Step-by-Step File Cleanup Process
 
-### 0. Identify Files for Cleanup
+### Step 0: Identify Target Files
 
 Target only modified TypeScript/JavaScript files:
 
 ```bash
 git status --porcelain | grep -E '\.(ts|tsx|js|jsx)$' | awk '{print $2}'
 ```
 
-### 1. Add Comments to All Functions
+**For each file, follow steps 1-6 in order:**
 
-**Every function requires a comment.**
+### Step 1: Add Comments to All Functions
+
+**Action**: Add a descriptive comment above every function (exported and internal).
+
+**What to do:**
+- Place a comment directly above each function declaration
+- Describe what the function does, not how it does it
+- Use present tense ("Creates", "Validates", "Displays")
+- Note: Internal functions should already have `_` prefix (see Step 2)
 
 ```typescript
 /**
@@ -35,7 +43,6 @@ export async function createUser(userData: CreateUserRequest): Promise<string> {
 
 /**
  * Validates email format using regex pattern.
- * Internal helper function for user validation.
  */
 function _validateEmail(email: string): boolean {
   // Implementation
@@ -49,25 +56,64 @@ export function UserProfile({ userId }: UserProfileProps) {
 }
 ```
 
-### 2. Prefix Internal Functions and Interfaces with Underscore
+### Step 2: Prefix Internal Elements with Underscore
 
-**All non-exported elements must be prefixed with `_`.**
+**Action**: Add `_` prefix to all non-exported functions, interfaces, types, and constants.
+
+**What to do:**
+- Scan through the file for any function, interface, type, or constant that is NOT exported
+- Add `_` prefix to the name
+- Update all references to use the new prefixed name
 
 ```typescript
 // Functions
 function _validateInput(input: string): boolean { }
 
-// Interfaces and Types
+// Interfaces and Types  
 interface _UserState { }
 type _ValidationResult = { };
 
 // Constants
 const _DEFAULT_TIMEOUT = 5000;
 ```
 
-### 3. File Organization Structure
+### Step 3: Eliminate All `any` Types
+
+**Action**: Replace every instance of `any` with proper types.
 
-**Organize file contents in this exact order:**
+**What to do:**
+- Search for all occurrences of `any` in the file
+- Replace with specific interfaces, types, or `unknown` with type guards
+- Use proper React event types and Convex context types
+
+```typescript
+// ❌ Replace this
+function processData(data: any): any { }
+
+// ✅ With this
+interface DataItem {
+  id: string;
+  value: number;
+}
+function processData(data: DataItem[]): number[] { }
+
+// ✅ Use proper event types
+function handleClick(event: React.MouseEvent<HTMLButtonElement>) { }
+
+// ✅ Use proper Convex context types
+import { type MutationCtx, type QueryCtx } from './_generated/server';
+```
+
+### Step 4: Reorganize File Structure
+
+**Action**: Rearrange the entire file contents in this exact order.
+
+**What to do:**
+1. Move all imports to the top (external libraries first, then internal imports)
+2. Move all exported interfaces and types to the top (after imports)
+3. Move all internal interfaces and types (prefixed with `_`) next
+4. Move all exported functions/components next
+5. Move all internal helper functions to the bottom
 
 ```typescript
 // 1. Imports (external first, then internal)
@@ -91,51 +137,15 @@ function _validateUserData(userData: CreateUserRequest): _ValidationResult { }
 function _formatDisplayName(firstName: string, lastName: string): string { }
 ```
 
-### 4. Replace `any` Types with Proper Types
-
-**Eliminate all `any` usage.**
-
-```typescript
-// ❌ Never use any
-function processData(data: any): any { }
-
-// ✅ Always use specific types
-interface DataItem {
-  id: string;
-  value: number;
-}
-function processData(data: DataItem[]): number[] { }
-
-// ✅ Use unknown and type guards for API responses
-function handleApiResponse(response: { data: unknown }) {
-  if (isValidData(response.data)) {
-    console.log(response.data);
-  }
-}
-
-// ✅ Use specific event types
-function handleClick(event: React.MouseEvent<HTMLButtonElement>) { }
-
-// ✅ Use proper Convex context types
-import { type MutationCtx, type QueryCtx } from './_generated/server';
-
-export const getUser = async (ctx: QueryCtx, args: { userId: string }) => { };
-export const createUser = async (ctx: MutationCtx, args: { name: string }) => { };
-```
-
-### 5. Prioritize High-Level Interfaces
-
-**Place most important interfaces at the top in this order:**
-1. Main entity interfaces
-2. Component props interfaces  
-3. API request/response interfaces
-4. Internal interfaces (prefixed with `_`)
+### Step 5: Apply React Performance Optimizations
 
-## React Performance Rules
+**Action**: Add `useCallback` and `useMemo` where appropriate.
 
-### Use useCallback and useMemo
-
-**Apply these hooks strategically:**
+**What to do:**
+- Wrap functions passed as props in `useCallback`
+- Wrap functions used as dependencies in other hooks in `useCallback`
+- Wrap expensive calculations in `useMemo`
+- **Do NOT** wrap primitive values or simple operations
 
 ```typescript
 // ✅ Use useCallback for functions passed as props
@@ -150,89 +160,106 @@ const analytics = useMemo(() => {
   }, {});
 }, [users, filter]);
 
-// ❌ Don't memoize primitive values or simple operations
+// ❌ Don't memoize these
 const displayName = `${user.firstName} ${user.lastName}`; // String - no useMemo
 const isAdult = user.age >= 18; // Boolean - no useMemo
 const count = users.length; // Number - no useMemo
-const isEmpty = !users.length; // Boolean - no useMemo
 ```
 
-**useCallback Required For:**
-- Functions passed as props to child components
-- Functions used as dependencies in other hooks
-
-**useMemo Required For:**
-- Expensive calculations or data transformations
-- Complex filtering, sorting, or data processing
+### Step 6: Final Quality Check
 
-**useMemo NOT Required For:**
-- Primitive values (boolean, string, number)
-- Simple property access or basic arithmetic
-- Array.length or basic object property checks
+**Action**: Verify the file meets all quality standards.
 
-## Quality Checklist
+**Checklist for each file:**
 
-**Before marking a file complete, verify:**
-
-### General
+**General Structure:**
 - [ ] All functions have descriptive comments
-- [ ] Non-exported items prefixed with `_`
-- [ ] Public interfaces at top, helpers at bottom
-- [ ] File organization follows exact structure
+- [ ] All non-exported items are prefixed with `_`
+- [ ] File follows the exact organization structure (imports → public types → internal types → exported functions → internal functions)
 
-### TypeScript
-- [ ] Zero usage of `any` type
-- [ ] Proper React event types
-- [ ] Convex functions use `QueryCtx`/`MutationCtx`
-- [ ] All parameters and returns explicitly typed
+**TypeScript Quality:**
+- [ ] Zero usage of `any` type anywhere in the file
+- [ ] All React event handlers use proper event types
+- [ ] All Convex functions use `QueryCtx`/`MutationCtx` types
+- [ ] All function parameters and return types are explicitly typed
 
-### React Performance  
-- [ ] `useCallback` for props and hook dependencies
-- [ ] `useMemo` for expensive operations only
-- [ ] No unnecessary memoization of simple values
+**React Performance:**
+- [ ] Functions passed as props are wrapped in `useCallback`
+- [ ] Functions used as hook dependencies are wrapped in `useCallback`
+- [ ] Expensive calculations are wrapped in `useMemo`
+- [ ] Simple values (strings, booleans, numbers) are NOT memoized
 
-## Example: Before and After
+## Complete Example: Before and After
 
-### Before
+### Before Cleanup
 ```typescript
 import React from 'react';
 
 function validateEmail(email: string) {
   return /\S+@\S+\.\S+/.test(email);
 }
 
-export function UserForm({ onSubmit }: UserFormProps) { }
+export function UserForm({ onSubmit }: UserFormProps) { 
+  const handleSubmit = (data: any) => {
+    if (validateEmail(data.email)) {
+      onSubmit(data);
+    }
+  };
+  return <form onSubmit={handleSubmit}>...</form>;
+}
 
 interface UserFormProps {
   onSubmit: (data: FormData) => void;
 }
 ```
 
-### After
+### After Cleanup (Following All 6 Steps)
 ```typescript
-import React from 'react';
+// 1. Imports
+import React, { useCallback } from 'react';
 
-/**
- * Props for the UserForm component.
- */
+// 2. Public interfaces
 export interface UserFormProps {
   onSubmit: (data: FormData) => void;
 }
 
+// 3. Internal types
+interface _FormData {
+  email: string;
+  name: string;
+}
+
+// 4. Exported components
 /**
  * User registration form with validation and submission handling.
  */
 export function UserForm({ onSubmit }: UserFormProps) {
-  // Implementation using helper functions below
+  /**
+   * Handles form submission with email validation.
+   */
+  const handleSubmit = useCallback((data: _FormData) => {
+    if (_validateEmail(data.email)) {
+      onSubmit(data);
+    }
+  }, [onSubmit]);
+
+  return <form onSubmit={handleSubmit}>...</form>;
 }
 
+// 5. Internal helper functions
 /**
  * Validates email format using regex pattern.
- * Internal helper function for form validation.
  */
 function _validateEmail(email: string): boolean {
   return /\S+@\S+\.\S+/.test(email);
 }
 ```
 
-This routine ensures code is maintainable, readable, and follows consistent patterns that make it easier for teams to collaborate and for AI agents to understand and work with the codebase.
+## Usage Instructions
+
+1. **Select a file** from your git status that needs cleanup
+2. **Work through steps 1-6** in exact order for that file
+3. **Complete the checklist** in Step 6 before moving to the next file
+4. **Repeat** for each file that needs cleanup
+
+This step-by-step approach ensures consistent, high-quality code that is maintainable and follows team standards.