Name: STRATEGIC_PLACEMENT_GUIDE
Author: WillWhittakerDHP

Prompt file imported from WillWhittakerDHP/LEGACY_DHP_Differential_Scheduler (.cursor/commands/comments/STRATEGIC_PLACEMENT_GUIDE.md). Copyright stays with the author.

Strategic Comment Placement Guide

Purpose: Guide for strategically placing STRUCTURED and REFERENCE comments at decision points to maximize learning value while minimizing cognitive load.

Context: Learning-focused code commentary system supporting WHAT/HOW/WHY structured comments and pattern references.

Overview

This guide helps you decide:

When to use STRUCTURED vs REFERENCE vs individual comment types
Where to place comments for maximum learning value
How to manage comment density to avoid cognitive overload

Comment Type Selection

STRUCTURED Comments

Use STRUCTURED comments for first occurrences and decision points:

✅ Function/component definitions with complex logic (>5 lines)
✅ Architectural pattern introductions
✅ Framework transition points (React → Vue)
✅ Complex type definitions
✅ State management decisions
✅ Significant architectural choices

Format:

/**
 * STRUCTURED: [Title]
 * 
 * WHAT: [What we're doing - the goal/purpose]
 * 
 * HOW: [How we're doing it - the approach/pattern]
 * 
 * WHY: [Why it works/why we chose this - the rationale]
 * 
 * SEE: [Optional reference to related pattern]
 */

REFERENCE Comments

Use REFERENCE comments for repeated patterns:

✅ Same pattern used in multiple places
✅ Minor variations of established patterns
✅ Following an architectural pattern explained elsewhere
✅ Framework patterns already documented

Format:

/**
 * REFERENCE: [Pattern Name]
 * See: [file-path::functionName or file-path:lineNumber]
 * 
 * [Brief note about any differences or variations]
 */

Individual Comment Types

Use individual types (LEARNING, WHY, COMPARISON, PATTERN, RESOURCE) for:

✅ Simple explanations that don't need full WHAT/HOW/WHY structure
✅ Quick clarifications
✅ Resource links
✅ Framework comparisons

Decision Point Identification

1. Function/Component Definitions

Criteria:

Functions with >5 lines of logic
Functions with multiple responsibilities
Functions with complex control flow
Functions making architectural decisions

Example - STRUCTURED:

/**
 * STRUCTURED: Vue Query Mutation Pattern
 * 
 * WHAT: Using Vue Query's useMutation for API updates with error handling
 * 
 * HOW: Following the mutation pattern with onSuccess/onError callbacks
 * 
 * WHY: Consistent error handling, loading states, and optimistic updates
 *      across all mutations. Better than manual fetch() calls.
 */
export function useEntityMutation<GE extends GlobalEntityKey>(
  entityKey: GE,
  method: 'POST' | 'PUT' | 'DELETE'
) {
  // Implementation...
}

Example - REFERENCE (if pattern exists elsewhere):

/**
 * REFERENCE: Entity Mutation Pattern
 * See: client-vue/src/composables/useEntity.ts::useEntityMutation
 * 
 * This mutation handles bulk operations with the same pattern.
 */
export function useBulkMutation<GE extends GlobalEntityKey>(entityKey: GE) {
  // Implementation...
}

2. Architectural Patterns

Criteria:

Composables (use* functions)
Context providers
Transformers
State management patterns

Example - STRUCTURED:

/**
 * STRUCTURED: Composable Pattern for Entity CRUD
 * 
 * WHAT: Higher-level composable providing convenient CRUD methods
 * 
 * HOW: Wraps low-level mutations with create/update/delete methods
 *      Uses Vue Query for caching and state management
 * 
 * WHY: Reduces boilerplate, provides consistent API, enables caching
 *      Similar to React hooks pattern but more integrated
 */
export function useEntityCrud<GE extends GlobalEntityKey>(entityKey: GE) {
  // Implementation...
}

3. Framework Transitions

Criteria:

React hooks → Vue equivalents
State management patterns
Effect patterns (useEffect → watchEffect)

Example - STRUCTURED:

/**
 * STRUCTURED: Vue.js Computed Properties
 * 
 * WHAT: Derived state that automatically updates when dependencies change
 * 
 * HOW: Using computed() function with reactive dependencies
 * 
 * WHY: Automatic dependency tracking prevents stale data bugs
 *      No manual dependency arrays like React's useMemo
 * 
 * COMPARISON: React: useMemo(() => value * 2, [value])
 *             Vue: computed(() => value.value * 2)
 */
const doubled = computed(() => value.value * 2);

4. Complex Logic Sections

Criteria:

Nested conditionals with business logic
Loops with complex transformations
Async operations with error handling
State machines or complex state transitions

Example - STRUCTURED:

/**
 * STRUCTURED: Error Handling Strategy
 * 
 * WHAT: Centralized error handling for API mutations
 * 
 * HOW: Using Vue Query's onError callback with error transformation
 * 
 * WHY: Consistent error handling across all mutations
 *      Transforms API errors to user-friendly messages
 */
const { mutateAsync } = useMutation({
  mutationFn: apiCall,
  onError: (error) => {
    // Error handling logic...
  }
});

5. Complex Type Definitions

Criteria:

Generic types with constraints
Union types with multiple variants
Mapped types
Complex type utilities

Example - STRUCTURED:

/**
 * STRUCTURED: Generic Entity Type System
 * 
 * WHAT: Type-safe entity system with runtime configuration
 * 
 * HOW: Using GlobalEntityKey with ENTITY_CONFIGS for runtime behavior
 * 
 * WHY: Maintains type safety while allowing dynamic entity management
 *      Avoids code duplication across entity types
 */
export type GlobalEntity<GE extends GlobalEntityKey> = EntityBase<GE> & {
  // Type definition...
};

Reference Usage Guidelines

When to Use References

Use REFERENCE when:

✅ Pattern is already explained elsewhere
✅ Usage is straightforward application of pattern
✅ Only minor variations exist
✅ Pattern is well-established in codebase

Don't use REFERENCE when:

❌ First occurrence of pattern
❌ Significant variations from original
❌ Reference would be unclear or ambiguous
❌ Pattern is simple enough that reference adds no value

Reference Format

Preferred formats:

file-path::functionName (e.g., useEntity.ts::useEntityMutation)
file-path:lineNumber (e.g., useEntity.ts:42)
Relative paths: ../composables/useEntity.ts::useEntityMutation

Examples:

// Good - Clear function reference
/**
 * REFERENCE: Entity Mutation Pattern
 * See: client-vue/src/composables/useEntity.ts::useEntityMutation
 */

// Good - Line number reference
/**
 * REFERENCE: Vue Query Setup
 * See: client-vue/src/composables/useQuery.ts:15
 */

// Good - Relative path
/**
 * REFERENCE: API Client Pattern
 * See: ../api/client.ts::createApiClient
 */

Cognitive Load Management

Density Guidelines

Strategic placement:

~1 STRUCTURED comment per function/component (at definition)
~1 REFERENCE comment per repeated pattern usage
Avoid comments on every line
Focus on decision points, not obvious code

Too dense (avoid):

// ❌ Too many comments
/**
 * STRUCTURED: Get user
 */
function getUser() {
  // ❌ Obvious - no comment needed
  return user;
}

/**
 * STRUCTURED: Set user
 */
function setUser(user: User) {
  // ❌ Obvious - no comment needed
  this.user = user;
}

Just right:

// ✅ Strategic placement at decision point
/**
 * STRUCTURED: User Authentication Flow
 * 
 * WHAT: Authenticate user and manage session state
 * 
 * HOW: Using JWT tokens with refresh mechanism
 * 
 * WHY: Secure, stateless authentication with automatic token refresh
 */
async function authenticateUser(credentials: Credentials) {
  // Implementation with clear logic...
}

Placement Strategy

Place comments:

✅ At function/component definitions
✅ Before complex logic blocks
✅ At architectural decision points
✅ Before framework transitions

Don't place comments:

❌ On every line
❌ On obvious code (getters, setters)
❌ Inside simple conditionals
❌ On import statements (unless explaining why)

Progression Pattern: STRUCTURED → REFERENCE

First Occurrence (STRUCTURED)

// File: client-vue/src/composables/useEntity.ts

/**
 * STRUCTURED: Entity Mutation Pattern
 * 
 * WHAT: Using Vue Query's useMutation for API updates
 * 
 * HOW: Following the mutation pattern with error handling
 * 
 * WHY: Consistent error handling and loading states
 */
export function useEntityMutation<GE extends GlobalEntityKey>(
  entityKey: GE,
  method: 'POST' | 'PUT' | 'DELETE'
) {
  // Full implementation...
}

Subsequent Occurrences (REFERENCE)

// File: client-vue/src/composables/useSchemaProp.ts

/**
 * REFERENCE: Entity Mutation Pattern
 * See: client-vue/src/composables/useEntity.ts::useEntityMutation
 * 
 * This mutation handles schema prop operations with the same pattern.
 */
export function useSchemaPropMutation(method: 'POST' | 'PUT' | 'DELETE') {
  // Implementation following same pattern...
}

Variation with Note (REFERENCE)

// File: client-vue/src/composables/useBulk.ts

/**
 * REFERENCE: Entity Mutation Pattern
 * See: client-vue/src/composables/useEntity.ts::useEntityMutation
 * 
 * Variation: Handles bulk operations instead of single entities.
 */
export function useBulkMutation<GE extends GlobalEntityKey>(entityKey: GE) {
  // Implementation with bulk-specific logic...
}

Before/After Examples

Before: No Comments

export function useEntityCrud<GE extends GlobalEntityKey>(entityKey: GE) {
  const { mutateAsync: createAsync } = useEntityMutation<GE>(entityKey, 'POST');
  const { mutateAsync: updateAsync } = useEntityMutation<GE>(entityKey, 'PUT');
  const { mutateAsync: deleteAsync } = useEntityMutation<GE>(entityKey, 'DELETE');
  
  const create = async (admin: GlobalEntity<GE>): Promise<GlobalEntity<GE> | undefined> => {
    const result = await createAsync({ admin });
    return result as GlobalEntity<GE> | undefined;
  };
  
  // More methods...
}

After: Strategic STRUCTURED Comment

/**
 * STRUCTURED: Higher-Level Entity CRUD Composable
 * 
 * WHAT: Convenient CRUD methods wrapping low-level mutations
 * 
 * HOW: Uses useEntityMutation for each operation type (POST/PUT/DELETE)
 * 
 * WHY: Reduces boilerplate, provides consistent API, enables caching
 *      Similar to React hooks pattern but more integrated
 */
export function useEntityCrud<GE extends GlobalEntityKey>(entityKey: GE) {
  const { mutateAsync: createAsync } = useEntityMutation<GE>(entityKey, 'POST');
  const { mutateAsync: updateAsync } = useEntityMutation<GE>(entityKey, 'PUT');
  const { mutateAsync: deleteAsync } = useEntityMutation<GE>(entityKey, 'DELETE');
  
  const create = async (admin: GlobalEntity<GE>): Promise<GlobalEntity<GE> | undefined> => {
    const result = await createAsync({ admin });
    return result as GlobalEntity<GE> | undefined;
  };
  
  // More methods...
}

Best Practices Summary

Use STRUCTURED at decision points - First occurrences, complex logic, architectural choices
Use REFERENCE for repeated patterns - Link to original explanation
Keep comments concise - 3-5 lines per section (WHAT/HOW/WHY)
Place strategically - At function definitions, not every line
Manage density - ~1 comment per function/component, focus on decision points
Use clear references - Format: file-path::functionName or file-path:lineNumber
Document variations - Note differences in REFERENCE comments

Related Documentation

Code Comments README - Complete command documentation
Quick Reference - Command lookup table
Learning Strategies - Learning-focused comment patterns

Install STRATEGIC_PLACEMENT_GUIDE and it becomes one more candidate the router can pick - when it fits.

A listing is a routing target with a manifest: what it does, which domains it covers, what it costs and who publishes it. Once installed it sits beside your own models and tools, is scored like any other candidate for each request, and shows up in the trace when it wins. Ratings come from workspaces that installed it, one per account.

# Strategic Comment Placement Guide **Purpose:** Guide for strategically placing STRUCTURED and REFERENCE comments at decision points to maximize learning value while minimizing cognitive load. **Context:** Learning-focused code commentary system supporting WHAT/HOW/WHY structured comments and pattern references. --- ## Overview This guide helps you decide: - **When** to use STRUCTURED vs REFERENCE vs individual comment types - **Where** to place comments for maximum learning value - **How** to manage comment density to avoid cognitive overload --- ## Comment Type Selection ### STRUCTURED Comments Use STRUCTURED comments for **first occurrences** and **decision points**: - ✅ Function/component definitions with complex logic (>5 lines) - ✅ Architectural pattern introductions - ✅ Framework transition points (React → Vue) - ✅ Complex type definitions - ✅ State management decisions - ✅ Significant architectural choices **Format:** ```typescript /** * STRUCTURED: [Title] * * WHAT: [What we're doing - the goal/purpose] * * HOW: [How we're doing it - the approach/pattern] * * WHY: [Why it works/why we chose this - the rationale] * * SEE: [Optional reference to related pattern] */ ``` ### REFERENCE Comments Use REFERENCE comments for **repeated patterns**: - ✅ Same pattern used in multiple places - ✅ Minor variations of established patterns - ✅ Following an architectural pattern explained elsewhere - ✅ Framework patterns already documented **Format:** ```typescript /** * REFERENCE: [Pattern Name] * See: [file-path::functionName or file-path:lineNumber] * * [Brief note about any differences or variations] */ ``` ### Individual Comment Types Use individual types (LEARNING, WHY, COMPARISON, PATTERN, RESOURCE) for: - ✅ Simple explanations that don't need full WHAT/HOW/WHY structure - ✅ Quick clarifications - ✅ Resource links - ✅ Framework comparisons --- ## Decision Point Identification ### 1. Function/Component Definitions **Criteria:** - Functions with >5 lines of logic - Functions with multiple responsibilities - Functions with complex control flow - Functions making architectural decisions **Example - STRUCTURED:** ```typescript /** * STRUCTURED: Vue Query Mutation Pattern * * WHAT: Using Vue Query's useMutation for API updates with error handling * * HOW: Following the mutation pattern with onSuccess/onError callbacks * * WHY: Consistent error handling, loading states, and optimistic updates * across all mutations. Better than manual fetch() calls. */ export function useEntityMutation<GE extends GlobalEntityKey>( entityKey: GE, method: 'POST' | 'PUT' | 'DELETE' ) { // Implementation... } ``` **Example - REFERENCE (if pattern exists elsewhere):** ```typescript /** * REFERENCE: Entity Mutation Pattern * See: client-vue/src/composables/useEntity.ts::useEntityMutation * * This mutation handles bulk operations with the same pattern. */ export function useBulkMutation<GE extends GlobalEntityKey>(entityKey: GE) { // Implementation... } ``` ### 2. Architectural Patterns **Criteria:** - Composables (use* functions) - Context providers - Transformers - State management patterns **Example - STRUCTURED:** ```typescript /** * STRUCTURED: Composable Pattern for Entity CRUD * * WHAT: Higher-level composable providing convenient CRUD methods * * HOW: Wraps low-level mutations with create/update/delete methods * Uses Vue Query for caching and state management * * WHY: Reduces boilerplate, provides consistent API, enables caching * Similar to React hooks pattern but more integrated */ export function useEntityCrud<GE extends GlobalEntityKey>(entityKey: GE) { // Implementation... } ``` ### 3. Framework Transitions **Criteria:** - React hooks → Vue equivalents - State management patterns - Effect patterns (useEffect → watchEffect) **Example - STRUCTURED:** ```typescript /** * STRUCTURED: Vue.js Computed Properties * * WHAT: Derived state that automatically updates when dependencies change * * HOW: Using computed() function with reactive dependencies * * WHY: Automatic dependency tracking prevents stale data bugs * No manual dependency arrays like React's useMemo * * COMPARISON: React: useMemo(() => value * 2, [value]) * Vue: computed(() => value.value * 2) */ const doubled = computed(() => value.value * 2); ``` ### 4. Complex Logic Sections **Criteria:** - Nested conditionals with business logic - Loops with complex transformations - Async operations with error handling - State machines or complex state transitions **Example - STRUCTURED:** ```typescript /** * STRUCTURED: Error Handling Strategy * * WHAT: Centralized error handling for API mutations * * HOW: Using Vue Query's onError callback with error transformation * * WHY: Consistent error handling across all mutations * Transforms API errors to user-friendly messages */ const { mutateAsync } = useMutation({ mutationFn: apiCall, onError: (error) => { // Error handling logic... } }); ``` ### 5. Complex Type Definitions **Criteria:** - Generic types with constraints - Union types with multiple variants - Mapped types - Complex type utilities **Example - STRUCTURED:** ```typescript /** * STRUCTURED: Generic Entity Type System * * WHAT: Type-safe entity system with runtime configuration * * HOW: Using GlobalEntityKey with ENTITY_CONFIGS for runtime behavior * * WHY: Maintains type safety while allowing dynamic entity management * Avoids code duplication across entity types */ export type GlobalEntity<GE extends GlobalEntityKey> = EntityBase<GE> & { // Type definition... }; ``` --- ## Reference Usage Guidelines ### When to Use References **Use REFERENCE when:** - ✅ Pattern is already explained elsewhere - ✅ Usage is straightforward application of pattern - ✅ Only minor variations exist - ✅ Pattern is well-established in codebase **Don't use REFERENCE when:** - ❌ First occurrence of pattern - ❌ Significant variations from original - ❌ Reference would be unclear or ambiguous - ❌ Pattern is simple enough that reference adds no value ### Reference Format **Preferred formats:** - `file-path::functionName` (e.g., `useEntity.ts::useEntityMutation`) - `file-path:lineNumber` (e.g., `useEntity.ts:42`) - Relative paths: `../composables/useEntity.ts::useEntityMutation` **Examples:** ```typescript // Good - Clear function reference /** * REFERENCE: Entity Mutation Pattern * See: client-vue/src/composables/useEntity.ts::useEntityMutation */ // Good - Line number reference /** * REFERENCE: Vue Query Setup * See: client-vue/src/composables/useQuery.ts:15 */ // Good - Relative path /** * REFERENCE: API Client Pattern * See: ../api/client.ts::createApiClient */ ``` --- ## Cognitive Load Management ### Density Guidelines **Strategic placement:** - ~1 STRUCTURED comment per function/component (at definition) - ~1 REFERENCE comment per repeated pattern usage - Avoid comments on every line - Focus on decision points, not obvious code **Too dense (avoid):** ```typescript // ❌ Too many comments /** * STRUCTURED: Get user */ function getUser() { // ❌ Obvious - no comment needed return user; } /** * STRUCTURED: Set user */ function setUser(user: User) { // ❌ Obvious - no comment needed this.user = user; } ``` **Just right:** ```typescript // ✅ Strategic placement at decision point /** * STRUCTURED: User Authentication Flow * * WHAT: Authenticate user and manage session state * * HOW: Using JWT tokens with refresh mechanism * * WHY: Secure, stateless authentication with automatic token refresh */ async function authenticateUser(credentials: Credentials) { // Implementation with clear logic... } ``` ### Placement Strategy **Place comments:** - ✅ At function/component definitions - ✅ Before complex logic blocks - ✅ At architectural decision points - ✅ Before framework transitions **Don't place comments:** - ❌ On every line - ❌ On obvious code (getters, setters) - ❌ Inside simple conditionals - ❌ On import statements (unless explaining why) --- ## Progression Pattern: STRUCTURED → REFERENCE ### First Occurrence (STRUCTURED) ```typescript // File: client-vue/src/composables/useEntity.ts /** * STRUCTURED: Entity Mutation Pattern * * WHAT: Using Vue Query's useMutation for API updates * * HOW: Following the mutation pattern with error handling * * WHY: Consistent error handling and loading states */ export function useEntityMutation<GE extends GlobalEntityKey>( entityKey: GE, method: 'POST' | 'PUT' | 'DELETE' ) { // Full implementation... } ``` ### Subsequent Occurrences (REFERENCE) ```typescript // File: client-vue/src/composables/useSchemaProp.ts /** * REFERENCE: Entity Mutation Pattern * See: client-vue/src/composables/useEntity.ts::useEntityMutation * * This mutation handles schema prop operations with the same pattern. */ export function useSchemaPropMutation(method: 'POST' | 'PUT' | 'DELETE') { // Implementation following same pattern... } ``` ### Variation with Note (REFERENCE) ```typescript // File: client-vue/src/composables/useBulk.ts /** * REFERENCE: Entity Mutation Pattern * See: client-vue/src/composables/useEntity.ts::useEntityMutation * * Variation: Handles bulk operations instead of single entities. */ export function useBulkMutation<GE extends GlobalEntityKey>(entityKey: GE) { // Implementation with bulk-specific logic... } ``` --- ## Before/After Examples ### Before: No Comments ```typescript export function useEntityCrud<GE extends GlobalEntityKey>(entityKey: GE) { const { mutateAsync: createAsync } = useEntityMutation<GE>(entityKey, 'POST'); const { mutateAsync: updateAsync } = useEntityMutation<GE>(entityKey, 'PUT'); const { mutateAsync: deleteAsync } = useEntityMutation<GE>(entityKey, 'DELETE'); const create = async (admin: GlobalEntity<GE>): Promise<GlobalEntity<GE> | undefined> => { const result = await createAsync({ admin }); return result as GlobalEntity<GE> | undefined; }; // More methods... } ``` ### After: Strategic STRUCTURED Comment ```typescript /** * STRUCTURED: Higher-Level Entity CRUD Composable * * WHAT: Convenient CRUD methods wrapping low-level mutations * * HOW: Uses useEntityMutation for each operation type (POST/PUT/DELETE) * * WHY: Reduces boilerplate, provides consistent API, enables caching * Similar to React hooks pattern but more integrated */ export function useEntityCrud<GE extends GlobalEntityKey>(entityKey: GE) { const { mutateAsync: createAsync } = useEntityMutation<GE>(entityKey, 'POST'); const { mutateAsync: updateAsync } = useEntityMutation<GE>(entityKey, 'PUT'); const { mutateAsync: deleteAsync } = useEntityMutation<GE>(entityKey, 'DELETE'); const create = async (admin: GlobalEntity<GE>): Promise<GlobalEntity<GE> | undefined> => { const result = await createAsync({ admin }); return result as GlobalEntity<GE> | undefined; }; // More methods... } ``` --- ## Best Practices Summary 1. **Use STRUCTURED at decision points** - First occurrences, complex logic, architectural choices 2. **Use REFERENCE for repeated patterns** - Link to original explanation 3. **Keep comments concise** - 3-5 lines per section (WHAT/HOW/WHY) 4. **Place strategically** - At function definitions, not every line 5. **Manage density** - ~1 comment per function/component, focus on decision points 6. **Use clear references** - Format: `file-path::functionName` or `file-path:lineNumber` 7. **Document variations** - Note differences in REFERENCE comments --- ## Related Documentation - [Code Comments README](./README.md) - Complete command documentation - [Quick Reference](./QUICK_REFERENCE.md) - Command lookup table - [Learning Strategies](../../../LEARNING_STRATEGIES.md) - Learning-focused comment patterns

{ "prompt": "# Strategic Comment Placement Guide\n\n**Purpose:** Guide for strategically placing STRUCTURED and REFERENCE comments at decision points to maximize learning value while minimizing cognitive load.\n\n**Context:** Learning-focused code commentary system supporting WHAT/HOW/WHY structured comments and pattern references.\n\n---\n\n## Overview\n\nThis guide helps you decide:\n- **When** to use STRUCTURED vs REFERENCE vs individual comment types\n- **Where** to place comments for maximum learning value\n- **How** to manage comment density to avoid cognitive overload\n\n---\n\n## Comment Type Selection\n\n### STRUCTURED Comments\n\nUse STRUCTURED comments for **first occurrences** and **decision points**:\n\n- ✅ Function/component definitions with complex logic (>5 lines)\n- ✅ Architectural pattern introductions\n- ✅ Framework transition points (React → Vue)\n- ✅ Complex type definitions\n- ✅ State management decisions\n- ✅ Significant architectural choices\n\n**Format:**\n```typescript\n/**\n * STRUCTURED: [Title]\n * \n * WHAT: [What we're doing - the goal/purpose]\n * \n * HOW: [How we're doing it - the approach/pattern]\n * \n * WHY: [Why it works/why we chose this - the rationale]\n * \n * SEE: [Optional reference to related pattern]\n */\n```\n\n### REFERENCE Comments\n\nUse REFERENCE comments for **repeated patterns**:\n\n- ✅ Same pattern used in multiple places\n- ✅ Minor variations of established patterns\n- ✅ Following an architectural pattern explained elsewhere\n- ✅ Framework patterns already documented\n\n**Format:**\n```typescript\n/**\n * REFERENCE: [Pattern Name]\n * See: [file-path::functionName or file-path:lineNumber]\n * \n * [Brief note about any differences or variations]\n */\n```\n\n### Individual Comment Types\n\nUse individual types (LEARNING, WHY, COMPARISON, PATTERN, RESOURCE) for:\n\n- ✅ Simple explanations that don't need full WHAT/HOW/WHY structure\n- ✅ Quick clarifications\n- ✅ Resource links\n- ✅ Framework comparisons\n\n---\n\n## Decision Point Identification\n\n### 1. Function/Component Definitions\n\n**Criteria:**\n- Functions with >5 lines of logic\n- Functions with multiple responsibilities\n- Functions with complex control flow\n- Functions making architectural decisions\n\n**Example - STRUCTURED:**\n```typescript\n/**\n * STRUCTURED: Vue Query Mutation Pattern\n * \n * WHAT: Using Vue Query's useMutation for API updates with error handling\n * \n * HOW: Following the mutation pattern with onSuccess/onError callbacks\n * \n * WHY: Consistent error handling, loading states, and optimistic updates\n * across all mutations. Better than manual fetch() calls.\n */\nexport function useEntityMutation<GE extends GlobalEntityKey>(\n entityKey: GE,\n method: 'POST' | 'PUT' | 'DELETE'\n) {\n // Implementation...\n}\n```\n\n**Example - REFERENCE (if pattern exists elsewhere):**\n```typescript\n/**\n * REFERENCE: Entity Mutation Pattern\n * See: client-vue/src/composables/useEntity.ts::useEntityMutation\n * \n * This mutation handles bulk operations with the same pattern.\n */\nexport function useBulkMutation<GE extends GlobalEntityKey>(entityKey: GE) {\n // Implementation...\n}\n```\n\n### 2. Architectural Patterns\n\n**Criteria:**\n- Composables (use* functions)\n- Context providers\n- Transformers\n- State management patterns\n\n**Example - STRUCTURED:**\n```typescript\n/**\n * STRUCTURED: Composable Pattern for Entity CRUD\n * \n * WHAT: Higher-level composable providing convenient CRUD methods\n * \n * HOW: Wraps low-level mutations with create/update/delete methods\n * Uses Vue Query for caching and state management\n * \n * WHY: Reduces boilerplate, provides consistent API, enables caching\n * Similar to React hooks pattern but more integrated\n */\nexport function useEntityCrud<GE extends GlobalEntityKey>(entityKey: GE) {\n // Implementation...\n}\n```\n\n### 3. Framework Transitions\n\n**Criteria:**\n- React hooks → Vue equivalents\n- State management patterns\n- Effect patterns (useEffect → watchEffect)\n\n**Example - STRUCTURED:**\n```typescript\n/**\n * STRUCTURED: Vue.js Computed Properties\n * \n * WHAT: Derived state that automatically updates when dependencies change\n * \n * HOW: Using computed() function with reactive dependencies\n * \n * WHY: Automatic dependency tracking prevents stale data bugs\n * No manual dependency arrays like React's useMemo\n * \n * COMPARISON: React: useMemo(() => value * 2, [value])\n * Vue: computed(() => value.value * 2)\n */\nconst doubled = computed(() => value.value * 2);\n```\n\n### 4. Complex Logic Sections\n\n**Criteria:**\n- Nested conditionals with business logic\n- Loops with complex transformations\n- Async operations with error handling\n- State machines or complex state transitions\n\n**Example - STRUCTURED:**\n```typescript\n/**\n * STRUCTURED: Error Handling Strategy\n * \n * WHAT: Centralized error handling for API mutations\n * \n * HOW: Using Vue Query's onError callback with error transformation\n * \n * WHY: Consistent error handling across all mutations\n * Transforms API errors to user-friendly messages\n */\nconst { mutateAsync } = useMutation({\n mutationFn: apiCall,\n onError: (error) => {\n // Error handling logic...\n }\n});\n```\n\n### 5. Complex Type Definitions\n\n**Criteria:**\n- Generic types with constraints\n- Union types with multiple variants\n- Mapped types\n- Complex type utilities\n\n**Example - STRUCTURED:**\n```typescript\n/**\n * STRUCTURED: Generic Entity Type System\n * \n * WHAT: Type-safe entity system with runtime configuration\n * \n * HOW: Using GlobalEntityKey with ENTITY_CONFIGS for runtime behavior\n * \n * WHY: Maintains type safety while allowing dynamic entity management\n * Avoids code duplication across entity types\n */\nexport type GlobalEntity<GE extends GlobalEntityKey> = EntityBase<GE> & {\n // Type definition...\n};\n```\n\n---\n\n## Reference Usage Guidelines\n\n### When to Use References\n\n**Use REFERENCE when:**\n- ✅ Pattern is already explained elsewhere\n- ✅ Usage is straightforward application of pattern\n- ✅ Only minor variations exist\n- ✅ Pattern is well-established in codebase\n\n**Don't use REFERENCE when:**\n- ❌ First occurrence of pattern\n- ❌ Significant variations from original\n- ❌ Reference would be unclear or ambiguous\n- ❌ Pattern is simple enough that reference adds no value\n\n### Reference Format\n\n**Preferred formats:**\n- `file-path::functionName` (e.g., `useEntity.ts::useEntityMutation`)\n- `file-path:lineNumber` (e.g., `useEntity.ts:42`)\n- Relative paths: `../composables/useEntity.ts::useEntityMutation`\n\n**Examples:**\n```typescript\n// Good - Clear function reference\n/**\n * REFERENCE: Entity Mutation Pattern\n * See: client-vue/src/composables/useEntity.ts::useEntityMutation\n */\n\n// Good - Line number reference\n/**\n * REFERENCE: Vue Query Setup\n * See: client-vue/src/composables/useQuery.ts:15\n */\n\n// Good - Relative path\n/**\n * REFERENCE: API Client Pattern\n * See: ../api/client.ts::createApiClient\n */\n```\n\n---\n\n## Cognitive Load Management\n\n### Density Guidelines\n\n**Strategic placement:**\n- ~1 STRUCTURED comment per function/component (at definition)\n- ~1 REFERENCE comment per repeated pattern usage\n- Avoid comments on every line\n- Focus on decision points, not obvious code\n\n**Too dense (avoid):**\n```typescript\n// ❌ Too many comments\n/**\n * STRUCTURED: Get user\n */\nfunction getUser() {\n // ❌ Obvious - no comment needed\n return user;\n}\n\n/**\n * STRUCTURED: Set user\n */\nfunction setUser(user: User) {\n // ❌ Obvious - no comment needed\n this.user = user;\n}\n```\n\n**Just right:**\n```typescript\n// ✅ Strategic placement at decision point\n/**\n * STRUCTURED: User Authentication Flow\n * \n * WHAT: Authenticate user and manage session state\n * \n * HOW: Using JWT tokens with refresh mechanism\n * \n * WHY: Secure, stateless authentication with automatic token refresh\n */\nasync function authenticateUser(credentials: Credentials) {\n // Implementation with clear logic...\n}\n```\n\n### Placement Strategy\n\n**Place comments:**\n- ✅ At function/component definitions\n- ✅ Before complex logic blocks\n- ✅ At architectural decision points\n- ✅ Before framework transitions\n\n**Don't place comments:**\n- ❌ On every line\n- ❌ On obvious code (getters, setters)\n- ❌ Inside simple conditionals\n- ❌ On import statements (unless explaining why)\n\n---\n\n## Progression Pattern: STRUCTURED → REFERENCE\n\n### First Occurrence (STRUCTURED)\n\n```typescript\n// File: client-vue/src/composables/useEntity.ts\n\n/**\n * STRUCTURED: Entity Mutation Pattern\n * \n * WHAT: Using Vue Query's useMutation for API updates\n * \n * HOW: Following the mutation pattern with error handling\n * \n * WHY: Consistent error handling and loading states\n */\nexport function useEntityMutation<GE extends GlobalEntityKey>(\n entityKey: GE,\n method: 'POST' | 'PUT' | 'DELETE'\n) {\n // Full implementation...\n}\n```\n\n### Subsequent Occurrences (REFERENCE)\n\n```typescript\n// File: client-vue/src/composables/useSchemaProp.ts\n\n/**\n * REFERENCE: Entity Mutation Pattern\n * See: client-vue/src/composables/useEntity.ts::useEntityMutation\n * \n * This mutation handles schema prop operations with the same pattern.\n */\nexport function useSchemaPropMutation(method: 'POST' | 'PUT' | 'DELETE') {\n // Implementation following same pattern...\n}\n```\n\n### Variation with Note (REFERENCE)\n\n```typescript\n// File: client-vue/src/composables/useBulk.ts\n\n/**\n * REFERENCE: Entity Mutation Pattern\n * See: client-vue/src/composables/useEntity.ts::useEntityMutation\n * \n * Variation: Handles bulk operations instead of single entities.\n */\nexport function useBulkMutation<GE extends GlobalEntityKey>(entityKey: GE) {\n // Implementation with bulk-specific logic...\n}\n```\n\n---\n\n## Before/After Examples\n\n### Before: No Comments\n\n```typescript\nexport function useEntityCrud<GE extends GlobalEntityKey>(entityKey: GE) {\n const { mutateAsync: createAsync } = useEntityMutation<GE>(entityKey, 'POST');\n const { mutateAsync: updateAsync } = useEntityMutation<GE>(entityKey, 'PUT');\n const { mutateAsync: deleteAsync } = useEntityMutation<GE>(entityKey, 'DELETE');\n \n const create = async (admin: GlobalEntity<GE>): Promise<GlobalEntity<GE> | undefined> => {\n const result = await createAsync({ admin });\n return result as GlobalEntity<GE> | undefined;\n };\n \n // More methods...\n}\n```\n\n### After: Strategic STRUCTURED Comment\n\n```typescript\n/**\n * STRUCTURED: Higher-Level Entity CRUD Composable\n * \n * WHAT: Convenient CRUD methods wrapping low-level mutations\n * \n * HOW: Uses useEntityMutation for each operation type (POST/PUT/DELETE)\n * \n * WHY: Reduces boilerplate, provides consistent API, enables caching\n * Similar to React hooks pattern but more integrated\n */\nexport function useEntityCrud<GE extends GlobalEntityKey>(entityKey: GE) {\n const { mutateAsync: createAsync } = useEntityMutation<GE>(entityKey, 'POST');\n const { mutateAsync: updateAsync } = useEntityMutation<GE>(entityKey, 'PUT');\n const { mutateAsync: deleteAsync } = useEntityMutation<GE>(entityKey, 'DELETE');\n \n const create = async (admin: GlobalEntity<GE>): Promise<GlobalEntity<GE> | undefined> => {\n const result = await createAsync({ admin });\n return result as GlobalEntity<GE> | undefined;\n };\n \n // More methods...\n}\n```\n\n---\n\n## Best Practices Summary\n\n1. **Use STRUCTURED at decision points** - First occurrences, complex logic, architectural choices\n2. **Use REFERENCE for repeated patterns** - Link to original explanation\n3. **Keep comments concise** - 3-5 lines per section (WHAT/HOW/WHY)\n4. **Place strategically** - At function definitions, not every line\n5. **Manage density** - ~1 comment per function/component, focus on decision points\n6. **Use clear references** - Format: `file-path::functionName` or `file-path:lineNumber`\n7. **Document variations** - Note differences in REFERENCE comments\n\n---\n\n## Related Documentation\n\n- [Code Comments README](./README.md) - Complete command documentation\n- [Quick Reference](./QUICK_REFERENCE.md) - Command lookup table\n- [Learning Strategies](../../../LEARNING_STRATEGIES.md) - Learning-focused comment patterns", "variables": [], "notes": "This guide helps you decide: - **When** to use STRUCTURED vs REFERENCE vs individual comment types - **Where** to place comments for maximum learning value - **How** to manage comment density to avoid cognitive overload", "metadata": { "source": { "provider": "github-cursor-commands", "repository": "https://github.com/WillWhittakerDHP/LEGACY_DHP_Differential_Scheduler", "path": ".cursor/commands/comments/STRATEGIC_PLACEMENT_GUIDE.md", "ref": "1d1659501a23cb4a6156c6e70e8ceb86e55b5663", "url": "https://github.com/WillWhittakerDHP/LEGACY_DHP_Differential_Scheduler/blob/1d1659501a23cb4a6156c6e70e8ceb86e55b5663/.cursor/commands/comments/STRATEGIC_PLACEMENT_GUIDE.md", "key": "WillWhittakerDHP/LEGACY_DHP_Differential_Scheduler/.cursor/commands/comments/STRATEGIC_PLACEMENT_GUIDE.md" } } }

STRATEGIC_PLACEMENT_GUIDE

About

Strategic Comment Placement Guide

Overview

Comment Type Selection

STRUCTURED Comments

REFERENCE Comments

Individual Comment Types

Decision Point Identification

1. Function/Component Definitions

2. Architectural Patterns

3. Framework Transitions

4. Complex Logic Sections

5. Complex Type Definitions

Reference Usage Guidelines

When to Use References

Reference Format

Cognitive Load Management

Density Guidelines

Placement Strategy

Progression Pattern: STRUCTURED → REFERENCE

First Occurrence (STRUCTURED)

Subsequent Occurrences (REFERENCE)

Variation with Note (REFERENCE)

Before/After Examples

Before: No Comments

After: Strategic STRUCTURED Comment

Best Practices Summary

Related Documentation

Install STRATEGIC_PLACEMENT_GUIDE and it becomes one more candidate the router can pick - when it fits.

Use it

Manifest

Reviews