Comments and code readability

JavaScript comments and code readability are essential for maintaining clean, understandable, and maintainable code.

1. Types of Comments

Single-line comments: Use // for short, specific explanations or to comment out a line of code temporarily.

1// Initialize the counter
2let counter = 0;

Multi-line comments: Use /* ... */ for longer explanations or to provide more context, like describing functions or modules.

1/**
2 * Fetches user data from the API
3 * @param {number} userId - The ID of the user
4 * @returns {Promise<Object>} User data
5 */
6async function getUserData(userId) {
7    // ...
8}

2. Write Meaningful Comments

Explain why something is done, not just what is being done. The code should ideally be self-explanatory for the "what."
Avoid redundant comments. Comments should add value and not state the obvious.

1// Bad Comment
2let total = price * quantity; // Multiplying price by quantity
3
4// Good Comment
5let total = price * quantity; // Calculate the total cost for the order

3. Use Descriptive Names

Choose clear and descriptive variable, function, and class names that convey their purpose.

1// Not descriptive
2let x = 10;
3function getData() { }
4
5// Descriptive
6let maxRetries = 10;
7function fetchUserDataFromApi() { }

4. Consistent Indentation and Spacing

Maintain consistent indentation (usually 2 or 4 spaces).
Group related blocks of code with line breaks to improve readability.

1function processOrder(order) {
2    const items = order.items;
3    
4    items.forEach(item => {
5        if (item.inStock) {
6            item.process();
7        }
8    });
9
10    return true;
11}

5. Break Down Long Functions

Split long functions into smaller, more manageable functions. This helps with readability and reusability.

1// Instead of one long function:
2function processOrder(order) {
3    // Processing logic...
4    // Payment logic...
5    // Notification logic...
6}
7
8// Break it down:
9function processOrder(order) {
10    validateOrder(order);
11    processPayment(order);
12    sendOrderConfirmation(order);
13}
14

6. Use Consistent Naming Conventions

Follow camelCase for variables and functions (getUserData), PascalCase for classes (UserProfile), and uppercase with underscores for constants (MAX_RETRIES).

7. Add Documentation Comments

For larger projects, use JSDoc-style comments to provide details about functions, parameters, return types, etc.

1/**
2 * Adds two numbers together.
3 * @param {number} a - The first number.
4 * @param {number} b - The second number.
5 * @returns {number} The sum of the two numbers.
6 */
7function add(a, b) {
8    return a + b;
9}
10

By following these practices, you can ensure your JavaScript code is clean, readable, and easy for others (and your future self) to understand and maintain.

Basic operators

Conditional statements in javascript (if, else if, else, switch)