global-commenting

Write meaningful code comments that explain WHY rather than WHAT, focusing on business logic, non-obvious solutions, workarounds, and complex algorithms while keeping code self-documenting. Use this s

global
commenting

SKILL.md

GitHub

Global Commenting

When to use this skill:

  • When explaining business logic or domain-specific rules with ticket references
  • When documenting non-obvious implementation decisions
  • When describing workarounds for browser bugs or library limitations with bug report links
  • When explaining performance optimizations and their trade-offs with profiling data links
  • When documenting complex algorithms or calculations with Wikipedia/paper links
  • When noting security considerations or sensitive operations (OWASP recommendations)
  • When explaining data flow or architectural patterns (e.g., function called from multiple places)
  • When writing JSDoc comments for TypeScript/JavaScript public API functions
  • When writing docstrings for Python public functions (Google style)
  • When writing XML documentation for .NET public methods
  • When documenting public API functions or library interfaces
  • When reviewing code to determine if comments should be added or removed
  • When deciding whether to comment or refactor unclear code (prefer refactoring)
  • When replacing TODO/FIXME with issue tracker references

This Skill provides Claude Code with specific guidance on how to adhere to coding standards as they relate to how it should handle global commenting.

Instructions

For details, refer to the information provided in this file: global commenting