Implementing Consistent Commenting Protocols

# Implementing Consistent Commenting Protocols

## Description
Develop a structured approach to commenting that expedites code reviews and facilitates better collaboration among developers.

## Category
JavaScript Cursor Rules

## Rules

### General Commenting Guidelines
- **Purpose**: Ensure all comments are clear, concise, and provide meaningful context to the code.
- **Language**: Write comments in English to maintain consistency across the codebase.

### Inline Comments
- **Usage**: Use inline comments to explain complex logic or algorithms that are not immediately understandable.
- **Placement**: Place inline comments on the same line as the code they describe, separated by at least two spaces.
- **Format**: Begin inline comments with a capital letter and end with a period.

### Block Comments
- **Usage**: Use block comments to provide overviews of code sections, describe the purpose of a function, or explain the rationale behind a particular implementation.
- **Placement**: Place block comments above the code they describe.
- **Format**: Use the following structure for block comments:

  
  /**
   * [Brief description of the code section or function]
   *
   * [Detailed explanation, if necessary]
   *
   * @param {Type} paramName - Description of the parameter.
   * @returns {Type} Description of the return value.
   */
  ```

### Function Comments
- **Requirement**: Every function must have a comment block describing its purpose, parameters, and return value.
- **Format**: Use JSDoc-style comments for functions:

  
  /**
   * Calculates the sum of two numbers.
   *
   * @param {number} a - The first number.
   * @param {number} b - The second number.
   * @returns {number} The sum of the two numbers.
   */
  function add(a, b) {
    return a + b;
  }
  ```

### Class and Module Comments
- **Requirement**: Provide a comment block at the beginning of each class or module file describing its purpose and usage.
- **Format**: Use the following structure:

  
  /**
   * [Class/Module Name]
   *
   * [Description of the class/module's purpose and functionality]
   *
   * [Any additional notes or usage instructions]
   */
  ```

### Commenting Out Code
- **Guideline**: Avoid leaving commented-out code in the codebase. If code needs to be temporarily disabled, include a comment explaining why and set a reminder to remove it later.

### Documentation Comments
- **Requirement**: Use JSDoc comments to generate documentation for the codebase.
- **Tools**: Integrate tools like JSDoc to automate documentation generation.

### Consistency
- **Enforcement**: Ensure all team members follow these commenting protocols to maintain a consistent and readable codebase.
- **Review**: Include comment quality checks as part of the code review process.

By adhering to these commenting protocols, the team will enhance code readability, facilitate easier maintenance, and improve collaboration during code reviews.