comment-generator_skill

Overview

This skill generates clear, pragmatic code comments and docstrings for functions, classes, and complex logic. It focuses on adding value by explaining intent, parameters, returns, exceptions, and usage examples rather than restating obvious code. Use it to produce language-appropriate comment blocks for TypeScript, JavaScript, Python, Java, and similar languages. It emphasizes concise, maintainable documentation that developers will keep up to date.

How this skill works

The skill detects the programming language from file extension, syntax patterns, or user input, then chooses the appropriate comment style (JSDoc/TSDoc, Python docstrings, Java-style Javadoc, etc.). It generates summaries, parameter and return descriptions, exception notes, and optional examples, and inserts inline comments to explain nontrivial decisions. For complex code it adds section comments and TODO/FIXME markers where improvements or edge-case handling are needed.

When to use it

• When you want to add docstrings or JSDoc/TSDoc to functions or classes
• When you ask to "add comments", "document this code", or "explain with comments"
• When preparing public APIs, libraries, or modules for other developers
• When refactoring complex logic and you want inline rationale comments
• When writing examples or usage snippets for README or docs

Best practices

• Explain why, not just what — focus comments on intent and trade-offs
• Prefer concise one-line summaries plus short parameter/return descriptions
• Use language-appropriate formats (JSDoc/TSDoc, Python triple-quote docstrings, Javadoc)
• Avoid commenting obvious code and keep comments updated when code changes
• Add examples for public APIs and note exceptions and edge cases

Example use cases

• Add JSDoc to a TypeScript function to improve editor autocomplete and type hints
• Insert Python docstrings for a class with attributes and usage examples
• Annotate complex algorithms with inline comments explaining the rationale and complexity
• Document public methods with parameter, return, and throws information for API consumers
• Convert terse code into readable, maintainable code by adding section comments and TODO notes