- Update docs when changing code
- Mark deprecated functions
- Version documentation changes
- Review during code reviews
- Test examples to ensure they work
Generate documentation comments for your functions and methods.
Well-documented code is essential for maintainability and collaboration. Different languages have established conventions for documenting functions and methods.
JSDoc is the standard for documenting JavaScript code. It uses block comments with special tags.
/**
* 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);
}@param - Function parameter@returns or @return - Return value@throws or @exception - Exceptions thrown@example - Usage example@deprecated - Mark as deprecated@see - Reference to related functions@since - Version when added@async - Async functionPython uses triple-quoted strings immediately after function definitions. Common styles include Google, NumPy, and reStructuredText.
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 is the standard documentation format for Java. It generates HTML documentation from comments.
/**
* 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;
}Avoid documenting obvious things that the code already makes clear:
/**
* Gets the name
* @returns name
*/
getName() {
return this.name;
}/**
* Returns the user's full name
* formatted as "Last, First"
* @returns {string} Formatted name
*/
getFormattedName() {
return `${this.lastName}, ${this.firstName}`;
}Type Annotations:
{string} - String value{number} - Numeric value{boolean} - True/false{Array} - Array{Object} - Object{?string} - Nullable{string|number} - UnionCommon Tags:
@param - Parameters@returns - Return value@throws - Exceptions@example - Example usage@deprecated - Deprecation