Code Comment Generator
Generate documentation comments for your functions and methods.
Documentation Comment Standards
Well-documented code is essential for maintainability and collaboration. Different languages have established conventions for documenting functions and methods.
JSDoc (JavaScript/TypeScript)
JSDoc is the standard for documenting JavaScript code. It uses block comments with special tags.
Example: JSDoc
/**
* Calculates the total price including tax
* @param {number} price - The base price
* @param {number} taxRate - Tax rate as decimal (e.g., 0.08 for 8%)
* @returns {number} The total price with tax
* @throws {Error} If price is negative
* @example
* calculateTotal(100, 0.08) // returns 108
*/
function calculateTotal(price, taxRate) {
if (price < 0) throw new Error('Price cannot be negative');
return price * (1 + taxRate);
}Common JSDoc Tags:
@param- Function parameter@returnsor@return- Return value@throwsor@exception- Exceptions thrown@example- Usage example@deprecated- Mark as deprecated@see- Reference to related functions@since- Version when added@async- Async function
Python Docstrings
Python uses triple-quoted strings immediately after function definitions. Common styles include Google, NumPy, and reStructuredText.
Example: Python (Google Style)
def calculate_total(price, tax_rate, shipping=0):
"""Calculates the total price including tax and shipping.
Args:
price (float): The base price of the item
tax_rate (float): Tax rate as decimal (e.g., 0.08 for 8%)
shipping (float, optional): Shipping cost. Defaults to 0.
Returns:
float: The total price with tax and shipping
Raises:
ValueError: If price is negative
Example:
>>> calculate_total(100, 0.08, 10)
118.0
"""
if price < 0:
raise ValueError("Price cannot be negative")
return (price * (1 + tax_rate)) + shippingJavaDoc (Java)
JavaDoc is the standard documentation format for Java. It generates HTML documentation from comments.
Example: JavaDoc
/**
* Calculates the total price including tax and shipping.
*
* This method performs validation on the input price and
* throws an exception if invalid.
*
* @param price the base price of the item
* @param taxRate tax rate as decimal (e.g., 0.08 for 8%)
* @param shipping shipping cost to add
* @return the total price with tax and shipping
* @throws IllegalArgumentException if price is negative
* @see #calculateDiscount(double, double)
* @since 1.0
*/
public double calculateTotal(double price, double taxRate, double shipping) {
if (price < 0) {
throw new IllegalArgumentException("Price cannot be negative");
}
return (price * (1 + taxRate)) + shipping;
}Best Practices
- Start with a verb (Calculates, Returns, Validates)
- Be specific about what the function does
- Explain the "why" not just the "what"
- Keep it under 80 characters when possible
- Include type information
- Describe what the parameter represents
- Note optional parameters and defaults
- Specify valid ranges or values
- Document units (seconds, pixels, dollars)
- Show typical usage
- Include edge cases
- Use realistic values
- Keep examples simple and focused
- Make examples executable/testable
- Update docs when changing code
- Mark deprecated functions
- Version documentation changes
- Review during code reviews
- Test examples to ensure they work
What NOT to Document
Avoid documenting obvious things that the code already makes clear:
Bad
/**
* Gets the name
* @returns name
*/
getName() {
return this.name;
}Good
/**
* Returns the user's full name
* formatted as "Last, First"
* @returns {string} Formatted name
*/
getFormattedName() {
return `${this.lastName}, ${this.firstName}`;
}Quick Reference
Type Annotations:
{string}- String value{number}- Numeric value{boolean}- True/false{Array}- Array{Object}- Object{?string}- Nullable{string|number}- Union
Common Tags:
@param- Parameters@returns- Return value@throws- Exceptions@example- Example usage@deprecated- Deprecation
Documentation Tools
- JavaScript: JSDoc, TypeDoc
- Python: Sphinx, pdoc
- Java: JavaDoc
- C#: XML Documentation
- Ruby: RDoc, YARD
- PHP: phpDocumentor