Document intent clearly

Add clear documentation that explains not just what code does, but why certain approaches were chosen. This applies to:

1. Complex code sections: Add explanatory comments to complex logic, particularly SQL queries

   -- last-used-api-keys: retrieves timestamp of most recent API key usage by role
   SELECT unix_millis(max(timestamp)) as timestamp, payload.role, payload.signature_prefix 
   FROM edge_logs cross join unnest(metadata) as m 
   -- additional joins...
   

2. Implementation decisions: Document the reasoning behind specific coding patterns

   // Create a shallow copy to prevent unintended mutations to the original object
   custom_properties: 'properties' in event ? event.properties : {},
   

3. UI elements: Include tooltips for interactive elements to clarify their purpose

4. Technical limitations: Explicitly state constraints in user-facing documentation (e.g., “disk size can only be expanded, not shrunk”)

Well-documented code improves maintainability, reduces onboarding time for new developers, and prevents misunderstandings about system behavior.