comments-javascript

JavaScript Comments Standards

File Headers

Required format for all JavaScript/TypeScript files:

/**
 * @file [Brief file description]
 * @fileoverview [Detailed explanation of the file's purpose and functionality]
 *
 * [Additional context and important notes about the file]
 *
 * Functions:
 * - [List all functions included in this file with brief descriptions]
 * - Format: "functionName: brief description"
 * - Must be present even if empty
 *
 * Constants:
 * - [List all constants if the file defines them]
 * - Format: "CONSTANT_NAME: type - description"
 * - Must be present even if empty
 *
 * Flow:
 * 1. [Step one in execution flow]
 * 2. [Step two]
 * - Must describe the main flow of the file
 *
 * Error Handling:
 * - [Describe potential error cases and how they are managed]
 * - Format: "Error case: handling approach"
 * - Must describe all error scenarios
 *
 * @module [Module path or identifier]
 * @requires [Dependency name] - [Brief description]
 * @exports {Type} [Exported entity] - [Brief export description]
 */

Function Documentation

Required format for all functions and methods:

/**
 * [Short function description]
 *
 * [Detailed explanation of what the function does, including edge cases]
 *
 * @async (if applicable)
 * @function [functionName]
 * @param {Type} name - [Parameter description]
 * @returns {Type} [Return value description]
 * @throws {ErrorType} [Description of when this error occurs]
 * @example
 * // Example usage of the function
 * const result = myFunction(param);
 * // returns: expected output
 *
 * // Edge case example
 * const edgeResult = myFunction(edgeParam);
 * // returns: edge case output
 *
 */

Class Documentation

/**
 * [Class description]
 *
 * @class
 * @implements {Interface}
 * @augments ParentClass
 * @property {Type} propertyName - [Property description]
 * @example
 * const instance = new MyClass(config);
 * instance.method();
 * // returns: expected output
 *
 */