Explaining code

Help the user understand how code or a system works, or what a change does. Lead with the behavior in plain technical prose. Name the functions, components, data, APIs, and ownership boundaries that matter. Define a technical term when the user may not know it. Keep necessary detail, but cut preamble and filler.

Explaining how something works

Use the smallest view that makes the explanation easier to follow, or prose alone when prose is clearer:

• Logic or an algorithm → pseudocode
• Runtime order → call tree
• UI ownership → component tree with relevant state and module boundaries
• File ownership → shallow file tree
• Interaction, data flow, states, or architecture → a fenced diagram block

Diagram blocks