Clean code is a joy to work with. It is easy to understand, maintain, and extend. In this blog post, we'll explore some tips and best practices for writing clean code, using JavaScript as our example language.

Clean code is a term used to describe computer code that is easy to read, understand, and maintain. Clean code is written in a way that makes it simple, concise, and expressive. It follows a set of conventions, standards, and practices that make it easy to read and follow.

Clean code is free from complexity, redundancy, and other code smells and anti-patterns that can make it difficult to maintain, debug, and modify.

I can't overstate the importance of clean code. When code is easy to read and understand, it makes it easier for developers to work on the codebase. This can lead to increased productivity and reduced errors.

Also, when code is easy to maintain, it ensures that the codebase can be improved and updated over time. This is especially important for long-term projects where code must be maintained and updated for years to come.

1. DRY (Don't Repeat Yourself)

The DRY principle encourages you to avoid duplicating code. This helps to reduce the risk of errors and makes your code easier to maintain.

// Bad: Duplicated code
function calculateArea(length, width) {
  return length * width;
}

function calculatePerimeter(length, width) {
  return 2 * (length + width);
}

// Good: DRY principle applied
function calculateArea(length, width) {
  return length * width;
}

function calculatePerimeter(length, width) {
  return 2 * calculateArea(length, width);
}

2. Meaningful Variable Names

Use descriptive variable names that indicate the purpose of the variable. Avoid using single-letter variable names or abbreviations that are not widely understood. When you create a variable a function, give it a name that tells what it does. This eliminates the need for extra comments explaining what the variable or the function is.

// Bad: Unclear variable names
let a = 10;
let b = 20;
let c = a + b;

// Good: Meaningful variable names
let totalItems = 10;
let pricePerItem = 20;
let totalPrice = totalItems * pricePerItem;

3. Avoid Useless Comments

Comments should clarify the code, not repeat what is already obvious. If the code is self-explanatory, comments are unnecessary. Instead of adding comments everywhere, try to make your code self-explanatory by using good names.

// Bad: Useless comment
let totalPrice = totalItems * pricePerItem; // Calculates the total price

// Good: No need for a comment
let totalPrice = totalItems * pricePerItem;

4. Single Responsibility Principle (SRP)

Each function or class should have a single, well-defined responsibility. This makes it easier to understand, test, and maintain your code. A function should do one job and do it well.

This makes it easier to understand and fix if needed. It’s like having one tool for one task, like a pencil for writing and scissors for cutting.

// Bad: Multiple responsibilities
function processOrder(order) {
  calculateTotalPrice(order);
  sendOrderConfirmationEmail(order);
  updateInventory(order);
}

// Good: Single responsibility
function calculateTotalPrice(order) {
  // ...
}

function sendOrderConfirmationEmail(order) {
  // ...
}

function updateInventory(order) {
  // ...
}

5. Code Readability

Write code that is easy to read and understand. Use consistent indentation, whitespace, and formatting. 

Use spaces, indentation, and line breaks to keep your code neat.

Just like writing a paragraph, you should break your code into smaller pieces so it’s not all in one line.

// Bad: Unreadable code
let totalItems = 10;
let pricePerItem = 20;
let totalPrice = totalItems * pricePerItem;

// Good: Readable code
let totalItems = 10;
let pricePerItem = 20;

let totalPrice = totalItems * pricePerItem;

6. Writing Unit Tests

Unit tests ensure that individual components of your code work as expected. Writing unit tests helps to identify and fix bugs early in the development process.

// Sample unit test
const calculateArea = require('./areaCalculator');

describe('calculateArea', () => {
  it('should return the correct area for a rectangle', () => {
    expect(calculateArea(4, 5)).toBe(20);
  });
});

7. Clear Flow and Execution

Logically organize your code, making it easy to follow the flow of execution. Use meaningful variable names and comments to help guide the reader.

// Good: Clear flow and execution
function processOrder(order) {
  let totalPrice = calculateTotalPrice(order);
  sendOrderConfirmationEmail(order, totalPrice);
  updateInventory(order);
}

8. Organizing Files

Organize your code into files and folders based on functionality. This helps to keep your project organized and easy to navigate.

For example, you might have a utils folder for helper functions, a components folder for React components, and a services folder for API calls.

Here are examples of a good and a bad folder structure using a React project as an example:

// Bad folder structure
my - app /
├── App.js
├── index.js
├── components /
│   ├── Button.js
│   ├── Card.js
│   └── Navbar.js
├── containers /
│   ├── Home.js
│   ├── Login.js
│   └── Profile.js
├── pages /
│   ├── Home.js
│   ├── Login.js
│   └── Profile.js
└── utilities /
├── api.js
└── helpers.js

In this example, the project structure is organized around file types, such as components, containers, and pages.

However, this approach can lead to confusion and duplication, as it's not clear which files belong where. For example, the Home component is present in both the containers and pages folders. It can also make it challenging to find and modify code, as developers may need to navigate multiple folders to find the code they need.

// Good folder structure
my - app /
├── src /
│   ├── components /
│   │   ├── Button /
│   │   │   ├── Button.js
│   │   │   ├── Button.module.css
│   │   │   └── index.js
│   │   ├── Card /
│   │   │   ├── Card.js
│   │   │   ├── Card.module.css
│   │   │   └── index.js
│   │   └── Navbar /
│   │       ├── Navbar.js
│   │       ├── Navbar.module.css
│   │       └── index.js
│   ├── pages /
│   │   ├── Home /
│   │   │   ├── Home.js
│   │   │   ├── Home.module.css
│   │   │   └── index.js
│   │   ├── Login /
│   │   │   ├── Login.js
│   │   │   ├── Login.module.css
│   │   │   └── index.js
│   │   └── Profile /
│   │       ├── Profile.js
│   │       ├── Profile.module.css
│   │       └── index.js
│   ├── utils /
│   │   ├── api.js
│   │   └── helpers.js
│   ├── App.js
│   └── index.js
└── public /
├── index.html
└── favicon.ico

In this example, the project structure is organized around features, such as components, pages, and utils. Each feature has its folder, which contains all the files related to that feature.

9. Simplicity

And last comes simplicity. This is the toughest one to evaluate because it's subjective, it depends on the person who reads the code. But some guidelines we can follow are:

1. Can you easily understand what the program does at each line?

2. Do functions and variables have names that represent their responsibilities?

3. Is the code indented correctly and spaced with the same format all along the codebase?

4. Is there any documentation available for the code? Are comments used to explain complex parts of the program?

5. How quickly can you identify in which part of the codebase are certain features of the program? Can you delete/add new features without the need to modify many other parts of the code?

6. Does the code follow a modular approach, with different features separated into components?

7. Is code reused when possible?

8. Are the same architecture, design, and implementation decisions followed equally all along the codebase?

10. Only Expose and Consume the Data You Need

One important principle of writing clean code is to only expose and consume the information that is necessary for a particular task. This helps to reduce complexity, increase efficiency, and avoid errors that can arise from using unnecessary data.

When data that is not needed is exposed or consumed, it can lead to performance issues and make the code more difficult to understand and maintain.

Suppose you have an object with multiple properties, but you only need to use a few of them. One way to do this would be to reference the object and the specific properties every time you need them. But this can become verbose and error-prone, especially if the object is deeply nested. A cleaner and more efficient solution would be to use object destructuring to only expose and consume the information you need.

// Original object
const user = {
    id: 1,
    name: 'Alice',
    email: 'alice@example.com',
    age: 25,
    address: {
        street: '123 Main St',
        city: 'Anytown',
        state: 'CA',
        zip: '12345'
    }
};

// Only expose and consume the name and email properties
const { name, email } = user;

console.log(name); // 'Alice'
console.log(email); // 'alice@example.com'

Conclusion

These are just a few tips for writing clean code. By following these best practices, you can create code that is easier to understand, maintain, and extend, leading to a more enjoyable and productive development experience. Remember good documentation also helps the developer who wrote the code understand it better in the future but also makes it easier for other developers to read and understand the codebase. When code is well-documented, it can save time and effort in debugging and maintaining the code.