> ## Documentation Index
> Fetch the complete documentation index at: https://peacockindia.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Best Practices in Code Documentation and Formatting
> Learn the essentials of using JSDoc, and effective commenting, along with indentation and formatting best practices.
Effective documentation and consistent formatting are key to making code readable and maintainable. This guide covers the usage of JSDoc and the dos and don'ts of commenting and formatting.
## JSDoc for JavaScript
JSDoc is a popular tool for documenting JavaScript code. It helps in understanding the purpose of functions, parameters, and return types.
### Good JSDoc Example
```js theme={null}
/**
* Adds two numbers together.
* @param {number} a - The first number.
* @param {number} b - The second number.
* @returns {number} The sum of the two numbers.
*/
function sum(a, b) {
return a + b;
}
```
### Bad JSDoc Example
```js theme={null}
// Adds a and b
function sum(a, b) {
return a + b;
}
// Missing detailed JSDoc comment
```
## Proper Use of Multi-Line Comments
Multi-line comments are useful for providing detailed explanations or summarizing blocks of code.
### Good Multi-Line Commenting Practice
```js theme={null}
/**
* This function calculates the total price of an order
* including tax and discount. It applies a tax rate of 8%,
* and a discount rate is applied if applicable.
*
* @param {number} basePrice - The base price of the order.
* @param {boolean} hasDiscount - Indicates if the order has a discount.
* @returns {number} The total price after applying tax and discount.
*/
function calculateTotalPrice(basePrice, hasDiscount) {
const taxRate = 0.08;
let discount = 0;
if (hasDiscount) {
discount = basePrice * 0.1; // 10% discount
}
return basePrice + (basePrice * taxRate) - discount;
}
```
### Bad Multi-Line Commenting Practice
```js theme={null}
/*
This function calculates the price.
It has parameters.
It returns a number.
*/
function calculateTotalPrice(basePrice, hasDiscount) {
// The actual function code
}
// Non-informative, redundant comments
```
## Including Meaningful Comments & Avoiding Redundancy
Strategic comments enhance code clarity, but beware of redundancy. Prioritize meaningful insights to facilitate collaboration and understanding among developers.
### Good Practice
```js theme={null}
// Loop through users and apply discounts to eligible ones
users.forEach(user => {
if (user.isEligibleForDiscount()) {
applyDiscount(user);
}
});
```
```js theme={null}
// Calculate the area of a rectangle
function calculateArea(length, width) {
return length * width;
}
```
### Bad Practice
```js theme={null}
// Start a loop
users.forEach(user => {
// Check if the user is eligible for discount
if (user.isEligibleForDiscount()) {
// Apply discount to the user
applyDiscount(user);
}
});
// Redundant comments that simply restate the code
```
```js theme={null}
// Calculate area
function calculateArea(l, w) {
return l * w;
// Ambiguous and unhelpful comment
}
```
## Indentation and Formatting
Consistent indentation and formatting are crucial for readability.
### Good Practice
Use consistent indentation (e.g., 2 or 4 spaces) and follow a style guide.
```js theme={null}
function exampleFunction() {
if (condition) {
// code
}
}
```
### Bad Practice
Mixing tabs and spaces or inconsistent indentation.
```js theme={null}
function exampleFunction() {
if(condition){
// code
}
}
// Inconsistent indentation
```
## Consistent Formatting
Adhering to a consistent code formatting style across your project is important.
### Good Practice
Follow a formatting standard like Airbnb's JavaScript Style Guide or Google's JavaScript Style Guide.
### Bad Practice
Inconsistent naming conventions, brace styles, or line breaks.
***
Remember, the goal of these practices is to make your code as clear and maintainable as possible. Well-documented and formatted code not only benefits you but also your fellow developers who may work on your code in the future.