Creating Descriptive Function Signatures

---
description: Enforce the creation of descriptive and meaningful function signatures in JavaScript to enhance code readability and maintainability.
globs: ["**/*.js", "**/*.jsx", "**/*.ts", "**/*.tsx"]
tags: [javascript, function-signatures, readability, maintainability]
priority: 3
version: 1.0.0
---

# Creating Descriptive Function Signatures

## Context
In JavaScript projects, clear and descriptive function signatures are crucial for code readability and maintainability.

## Requirements
- **Use Descriptive Function Names**: Function names should clearly convey their purpose.
- **Employ JSDoc Annotations**: Document function behavior, parameters, and return values using JSDoc.
- **Adopt Consistent Naming Conventions**: Use clear and consistent parameter names that indicate their data types and purposes.

## Examples

<example>
/**
 * Calculates the total price of items in a cart.
 * @param {Array<{ price: number, quantity: number }>} items - Array of items with price and quantity.
 * @returns {number} Total price of all items.
 */
function calculateTotalPrice(items) {
  return items.reduce((total, item) => total + item.price * item.quantity, 0);
}
</example>

<example type="invalid">
function calc(items) {
  return items.reduce((t, i) => t + i.p * i.q, 0);
}
</example>