{"kind":"AgentDefinition","metadata":{"namespace":"community","name":"self-explanatory-code-commenting","version":"0.1.0"},"spec":{"agents_md":"---\ndescription: 'Guidelines for GitHub Copilot to write comments to achieve self-explanatory code with less comments. Examples are in JavaScript but it should work on any language that has comments.'\napplyTo: '**'\n---\n\n# Self-explanatory Code Commenting Instructions\n\n## Core Principle\n**Write code that speaks for itself. Comment only when necessary to explain WHY, not WHAT.**\nWe do not need comments most of the time.\n\n## Commenting Guidelines\n\n### ❌ AVOID These Comment Types\n\n**Obvious Comments**\n```javascript\n// Bad: States the obvious\nlet counter = 0;  // Initialize counter to zero\ncounter++;  // Increment counter by one\n```\n\n**Redundant Comments**\n```javascript\n// Bad: Comment repeats the code\nfunction getUserName() {\n    return user.name;  // Return the user's name\n}\n```\n\n**Outdated Comments**\n```javascript\n// Bad: Comment doesn't match the code\n// Calculate tax at 5% rate\nconst tax = price * 0.08;  // Actually 8%\n```\n\n### ✅ WRITE These Comment Types\n\n**Complex Business Logic**\n```javascript\n// Good: Explains WHY this specific calculation\n// Apply progressive tax brackets: 10% up to 10k, 20% above\nconst tax = calculateProgressiveTax(income, [0.10, 0.20], [10000]);\n```\n\n**Non-obvious Algorithms**\n```javascript\n// Good: Explains the algorithm choice\n// Using Floyd-Warshall for all-pairs shortest paths\n// because we need distances between all nodes\nfor (let k = 0; k \u003c vertices; k++) {\n    for (let i = 0; i \u003c vertices; i++) {\n        for (let j = 0; j \u003c vertices; j++) {\n            // ... implementation\n        }\n    }\n}\n```\n\n**Regex Patterns**\n```javascript\n// Good: Explains what the regex matches\n// Match email format: username@domain.extension\nconst emailPattern = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$/;\n```\n\n**API Constraints or Gotchas**\n```javascript\n// Good: Explains external constraint\n// GitHub API rate limit: 5000 requests/hour for authenticated users\nawait rateLimiter.wait();\nconst response = await fetch(githubApiUrl);\n```\n\n## Decision Framework\n\nBefore writing a comment, ask:\n1. **Is the code self-explanatory?** → No comment needed\n2. **Would a better variable/function name eliminate the need?** → Refactor instead\n3. **Does this explain WHY, not WHAT?** → Good comment\n4. **Will this help future maintainers?** → Good comment\n\n## Special Cases for Comments\n\n### Public APIs\n```javascript\n/**\n * Calculate compound interest using the standard formula.\n * \n * @param {number} principal - Initial amount invested\n * @param {number} rate - Annual interest rate (as decimal, e.g., 0.05 for 5%)\n * @param {number} time - Time period in years\n * @param {number} compoundFrequency - How many times per year interest compounds (default: 1)\n * @returns {number} Final amount after compound interest\n */\nfunction calculateCompoundInterest(principal, rate, time, compoundFrequency = 1) {\n    // ... implementation\n}\n```\n\n### Configuration and Constants\n```javascript\n// Good: Explains the source or reasoning\nconst MAX_RETRIES = 3;  // Based on network reliability studies\nconst API_TIMEOUT = 5000;  // AWS Lambda timeout is 15s, leaving buffer\n```\n\n### Annotations\n```javascript\n// TODO: Replace with proper user authentication after security review\n// FIXME: Memory leak in production - investigate connection pooling\n// HACK: Workaround for bug in library v2.1.0 - remove after upgrade\n// NOTE: This implementation assumes UTC timezone for all calculations\n// WARNING: This function modifies the original array instead of creating a copy\n// PERF: Consider caching this result if called frequently in hot path\n// SECURITY: Validate input to prevent SQL injection before using in query\n// BUG: Edge case failure when array is empty - needs investigation\n// REFACTOR: Extract this logic into separate utility function for reusability\n// DEPRECATED: Use newApiFunction() instead - this will be removed in v3.0\n```\n\n## Anti-Patterns to Avoid\n\n### Dead Code Comments\n```javascript\n// Bad: Don't comment out code\n// const oldFunction = () =\u003e { ... };\nconst newFunction = () =\u003e { ... };\n```\n\n### Changelog Comments\n```javascript\n// Bad: Don't maintain history in comments\n// Modified by John on 2023-01-15\n// Fixed bug reported by Sarah on 2023-02-03\nfunction processData() {\n    // ... implementation\n}\n```\n\n### Divider Comments\n```javascript\n// Bad: Don't use decorative comments\n//=====================================\n// UTILITY FUNCTIONS\n//=====================================\n```\n\n## Quality Checklist\n\nBefore committing, ensure your comments:\n- [ ] Explain WHY, not WHAT\n- [ ] Are grammatically correct and clear\n- [ ] Will remain accurate as code evolves\n- [ ] Add genuine value to code understanding\n- [ ] Are placed appropriately (above the code they describe)\n- [ ] Use proper spelling and professional language\n\n## Summary\n\nRemember: **The best comment is the one you don't need to write because the code is self-documenting.**\n","description":"Guidelines for GitHub Copilot to write comments to achieve self-explanatory code with less comments. Examples are in JavaScript but it should work on any language that has comments.","import":{"commit_sha":"541b7819d8c3545c6df122491af4fa1eae415779","imported_at":"2026-05-18T20:05:35Z","license_text":"MIT License\n\nCopyright GitHub, Inc.\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.","owner":"github","repo":"github/awesome-copilot","source_url":"https://github.com/github/awesome-copilot/blob/541b7819d8c3545c6df122491af4fa1eae415779/instructions/self-explanatory-code-commenting.instructions.md"},"manifest":{}},"content_hash":[40,69,247,58,134,51,46,143,185,62,75,245,142,168,29,111,208,145,68,139,176,56,250,84,149,39,176,45,236,173,36,209],"trust_level":"unsigned","yanked":false}