Add comments that explain the reasoning, intent, or context behind code decisions, especially for non-obvious logic, workarounds, or business requirements. Focus on the "why" rather than just the "what" to help future maintainers understand the decision-making process.
Add comments that explain the reasoning, intent, or context behind code decisions, especially for non-obvious logic, workarounds, or business requirements. Focus on the “why” rather than just the “what” to help future maintainers understand the decision-making process.
Examples of good explanatory comments:
// GitHub Code Scanning requires locations even when no file is provided, so we fall back to the path// bufferOutput: when true, captures raw buffer data for binary content processing// AWS uses cvssv3_baseScore, GitHub uses security-severity for CVSS scoring// We only filter displayed results to avoid affecting internal processing while cleaning up user-facing output// TODO: Make this optional once custom rules are implementedAvoid comments that simply restate what the code does. Instead, provide context about why certain approaches were taken, what constraints influenced the design, or what future considerations should be kept in mind.
Enter the URL of a public GitHub repository