In this guide, you'll build a complete Task Manager app with user authentication, protected routes, and full CRUD functionality, built with React on the frontend and Express/MongoDB on the backend.

This article will serve as your hands-on, code-first guide to building, securing, and deploying a MERN application, drawing from my own practical experience. Every section has code you can run, and I’ll give concise explanations along the way.

It doesn’t matter if you're just getting started with MERN or looking to level up your architecture and production deployment knowledge – this article is designed to get you from zero to production with confidence.

Table of Contents

• Prerequisites

  • Tools & Tech Stack

  • Skills & Setup

• Project Setup: Laying the Groundwork

  • Project Structure

  • Code Quality: Linting and Formatting

• Testing: Ensuring Robustness

  • Backend Testing (Node.js/Express.js)

  • Frontend Testing (React Testing Library + Cypress)

• How to Build the Task Manager

  • Backend Implementation (Node.js/Express.js)

  • Frontend Implementation (React)

• Deployment: From Localhost to Live

  • Backend Deployment (Node.js/Express.js)

  • Frontend Deployment (React)

  • Database Deployment (MongoDB Atlas)

  • 1. .env Configuration Example

  • 2. Connect to MongoDB in app.js

  • Other Deployment Options

• Security Best Practices: Fortifying Your Application

  • Setup Input Validation and Sanitization

  • Add Authentication and Authorization

  • Implement Rate Limiting

  • Setup CORS Configuration (Cross-Origin Resource Sharing)

  • Use Environment Variables

• Monitoring and Logging with Winston and Morgan

  • Frontend Error Monitoring (Sentry)

• Conclusion

Prerequisites

Before jumping in the project, here’s what you’ll need to get the most out of this tutorial:

Tools & Tech Stack

You’ll be using the following technologies throughout the project:

• Node.js & npm – Backend runtime and package manager

• Express.js – Web framework for Node

• MongoDB Atlas – Cloud-hosted NoSQL database

• Mongoose – ODM for MongoDB

• React – Frontend UI library

• React Router – For client-side routing

• Axios – For making API requests

• Jest & Supertest – For backend tests

• React Testing Library & Cypress – For Frontend unit and E2E tests

• ESLint + Prettier – For code formatting, linting

• Husky – To setup pre-commit hooks

• Helmet, Joi, express-rate-limit, cors – For security, validation, and best practices

• PM2 & NGINX – For backend deployment

• Sentry – For error monitoring

Skills & Setup

• Basic knowledge of JavaScript, React, and Node.js

• Familiarity with REST APIs and HTTP request/response flows

• Git and a GitHub account for version control

• A free MongoDB Atlas account

• Node.js and npm installed locally (Node 18+ recommended)

Project Setup: Laying the Groundwork

A well-structured project is crucial for maintainability. We'll adopt a clear separation between the front end and the back end here.

Project Structure

This structure clearly separates the React front end (client/) from the Node.js/Express.js back end (server/), promoting modularity and easier management.

my-mern-app/                # Root folder
├── client/                 # React frontend
│   ├── public/
│   ├── src/
│   │   ├── components/
│   │   ├── pages/
│   │   ├── App.js
│   │   └── index.js
│   └── package.json
├── server/                 # Node.js/Express.js backend
│   ├── config/
│   ├── controllers/
│   ├── models/
│   ├── routes/
│   ├── services/
│   ├── app.js
│   └── package.json

Code Quality: Linting and Formatting

Consistency is key when you’re building a production-grad application like this one. We'll use ESLint with Airbnb style and Prettier for automated code quality and formatting.

To install these tools, run this in your terminal:

npm install --save-dev eslint prettier eslint-config-airbnb-base eslint-plugin-prettier

And here are some setups with their recommended configurations:

This configuration sets up ESLint for a Node.js project using the Airbnb and Prettier style guides, with custom rules to relax strict linting constraints like allowing console.log and disabling mandatory function names.

.eslintrc.js (server-side example)

module.exports = {

  env: {

    node: true,

    commonjs: true,

    es2021: true,

  },

  extends: ["airbnb-base", "prettier"],

  plugins: ["prettier"],

  parserOptions: {

    ecmaVersion: 12,

  },

  rules: {

    "prettier/prettier": "error",

    "no-console": "off",

    "func-names": "off",

    "no-process-exit": "off",

    "class-methods-use-this": "off",

    "import/no-extraneous-dependencies": "off",

  },

};

.prettierrc

This config enforces consistent formatting: add semicolons, use trailing commas where valid, and prefer single quotes for strings.

{

  "semi": true,

  "trailingComma": "all",

  "singleQuote": true

}

Version Control: Git Essentials

Git is indispensable. You can use feature branches and pull requests for collaborative development, making it easier to work on large projects with coworkers. Consider using Husky for pre-commit hooks to enforce linting and testing.

Install Husky:

Install Husky to easily manage Git hooks, allowing you to automate tasks like linting and testing before commits.

npm install husky --save-dev

package.json (add script)

This package.json file sets up a Node.js project named my-mern-app, and configures a prepare script to install Git hooks using Husky (v7). It's ready for adding pre-commit automation, such as linting or testing.

{

  "name": "my-mern-app",

  "version": "1.0.0",

  "description": "",

  "main": "index.js",

  "scripts": {

    "prepare": "husky install"

  },

  "keywords": [],

  "author": "",

  "license": "ISC",

  "devDependencies": {

    "husky": "^7.0.0"

  }

}

Create a pre-commit hook

The below command sets up a pre-commit hook that automatically runs your tests and linter before each commit, ensuring code quality and preventing errors from entering your codebase.

npx husky add .husky/pre-commit "npm test && npm run lint"

Testing: Ensuring Robustness

Automated testing is vital. We'll cover unit, integration, and end-to-end testing in this guide.

Backend Testing (Node.js/Express.js)

You’ll use Jest for unit testing and Supertest for API integration tests.

Install them like this:

npm install --save-dev jest supertest

You’ll use Jest to write unit tests for your JavaScript code and Supertest to test HTTP requests against your Express.js API.

Example Test (server/tests/auth.test.js):

This test suite uses Supertest to simulate API calls for user registration and login, asserting that the responses have the expected status codes and properties.

const request = require('supertest');

const app = require('../app'); // Your Express app instance

describe('Auth API', () => {

  it('should register a new user', async () => {

    const res = await request(app)

      .post('/api/auth/register')

      .send({

        username: 'testuser',

        email: 'test@example.com',

        password: 'password123',

      });

    expect(res.statusCode).toEqual(201);

    expect(res.body).toHaveProperty('_id');

  });


  it('should login an existing user', async () => {

    const res = await request(app)

      .post('/api/auth/login')

      .send({

        email: 'test@example.com',

        password: 'password123',

      });

    expect(res.statusCode).toEqual(200);

    expect(res.headers['set-cookie']).toBeDefined();

  });

});

Frontend Testing (React Testing Library + Cypress)

You’ll use Jest and the React Testing Library for unit/integration tests, and Cypress for E2E tests.

You can install these like this:

npm install --save-dev @testing-library/react @testing-library/jest-dom jest cypress

React Testing Library will help you test your React components, and Cypress will provide comprehensive end-to-end testing of your frontend application.

Example Component Test (client/src/components/Button.test.js):

This unit test uses the React Testing Library to render a Button component and verifies that the specified text content is present in the rendered output.

import React from 'react';

import { render, screen } from '@testing-library/react';

import Button from './Button';


test('renders button with text', () => {

  render(<Button>Click Me</Button>);

  const buttonElement = screen.getByText(/Click Me/i);

  expect(buttonElement).toBeInTheDocument();

});

The following Cypress test simulates a complete user authentication flow, from registration to login and logout, asserting expected URL changes and page content.

Example E2E Test (cypress/e2e/auth.cy.js)

describe('Authentication Flow', () => {

  it('should allow a user to register and login', () => {

    cy.visit('/register');

    cy.get('input[name="username"]').type('e2euser');

    cy.get('input[name="email"]').type('e2e@example.com');

    cy.get('input[name="password"]').type('password123');

    cy.get('button[type="submit"]').click();

    cy.url().should('include', '/dashboard');

    cy.contains('Welcome, e2euser');

    cy.get('button').contains('Logout').click();

    cy.url().should('include', '/login');

    cy.get('input[name="email"]').type('e2e@example.com');

    cy.get('input[name="password"]').type('password123');

    cy.get('button[type="submit"]').click();

    cy.url().should('include', '/dashboard');

  });

});

How to Build the Task Manager

We'll build a simple Task Manager with user authentication and CRUD operations for tasks so you can see how the whole thing comes together.

Backend Implementation (Node.js/Express.js)

Dependencies

Start by installing our core backend libraries: Express for routing, Mongoose for MongoDB interactions, dotenv for environment variables, bcrypt/jsonwebtoken/cookie-parser for secure authentication, and helmet for setting secure HTTP headers:

npm install express mongoose dotenv bcryptjs jsonwebtoken cookie-parser

server/app.js (Entry Point)

Next, we’ll set up the first or the main entry point for the backend. This is the main Express.js application file, which configures middleware, establishes a MongoDB connection, and sets up API routes for authentication and task management.

const express = require('express');

const mongoose = require('mongoose');

const dotenv = require('dotenv');

const cookieParser = require('cookie-parser');

const helmet = require('helmet');

const authRoutes = require('./routes/authRoutes');

const taskRoutes = require('./routes/taskRoutes');

const { notFound, errorHandler } = require('./middleware/errorMiddleware');

dotenv.config();


const app = express();

app.use(helmet());

app.use(express.json());

app.use(cookieParser());


mongoose.connect(process.env.MONGO_URI)

  .then(() => console.log('MongoDB connected!'))

  .catch(err => console.error('MongoDB connection error:', err));


app.use('/api/auth', authRoutes);

app.use('/api/tasks', taskRoutes);


app.get('/', (req, res) => {

  res.send('MERN Task Manager API is running!');

});


app.use(notFound);

app.use(errorHandler);


const PORT = process.env.PORT || 5000;

app.listen(PORT, () => {

  console.log(`Server running on port ${PORT}`);

});

server/.env

To avoid hardcoding secrets, we’ll add a .env file where we can securely store environment variables, such as our database URI and JWT secret. This file stores sensitive environment variables such as your MongoDB connection string, server port, and JWT secret, keeping them secure and separate from your codebase.

MONGO_URI=your_mongodb_connection_string_here

PORT=5000

JWT_SECRET=supersecretjwtkey

server/models/User.js

Now, let’s define our User model using MongoDB. This schema includes fields for username, email, and password, with pre-save hooks for password hashing and a method for password comparison.

const mongoose = require('mongoose');

const bcrypt = require('bcryptjs');


const UserSchema = new mongoose.Schema({

  username: {

    type: String,

    required: true,

    unique: true,

  },

  email: {

    type: String,

    required: true,

    unique: true,

  },

  password: {

    type: String,

    required: true,

  },

});

UserSchema.pre('save', async function (next) {

  if (!this.isModified('password')) {

    next();

  }

  const salt = await bcrypt.genSalt(10);

  this.password = await bcrypt.hash(this.password, salt);

});


UserSchema.methods.matchPassword = async function (enteredPassword) {

  return await bcrypt.compare(enteredPassword, this.password);

};


module.exports = mongoose.model('User', UserSchema);

server/models/Task.js

Next, we’ll create the Task model. This schema defines the Task model, which links each task to a user and includes fields for title, description, completion status, and creation timestamp.

const mongoose = require('mongoose');


const TaskSchema = new mongoose.Schema({

  user: {

    type: mongoose.Schema.Types.ObjectId,

    ref: 'User',

    required: true,

  },

  title: {

    type: String,

    required: true,

    trim: true,

  },

  description: {

    type: String,

    trim: true,

  },

  completed: {

    type: Boolean,

    default: false,

  },

  createdAt: {

    type: Date,

    default: Date.now,

  },

});


module.exports = mongoose.model('Task', TaskSchema);

server/controllers/authController.js

Let’s build out the authentication controller. This controller handles user authentication flows, including registration, login, logout, and fetching user profiles, using JWTs and secure HTTP-only cookies.

const User = require('../models/User');

const jwt = require('jsonwebtoken');

const generateToken = (id) => {

  return jwt.sign({ id }, process.env.JWT_SECRET, {

    expiresIn: '1h',

  });

};

exports.registerUser = async (req, res) => {

  const { username, email, password } = req.body;

  try {

    const userExists = await User.findOne({ email });

    if (userExists) return res.status(400).json({ message: 'User already exists' });

    const user = await User.create({ username, email, password });

    if (user) {

      const token = generateToken(user._id);

      res.cookie('token', token, { httpOnly: true, secure: process.env.NODE_ENV === 'production', maxAge: 3600000 });

      res.status(201).json({ id: user.id, username: user.username, email: user.email });

    } else {

      res.status(400).json({ message: 'Invalid user data' });

    }

  } catch (error) {

    res.status(500).json({ message: error.message });

  }

};


exports.loginUser = async (req, res) => {

  const { email, password } = req.body;

  try {

    const user = await User.findOne({ email });

    if (user && (await user.matchPassword(password))) {

      const token = generateToken(user._id);

      res.cookie('token', token, { httpOnly: true, secure: process.env.NODE_ENV === 'production', maxAge: 3600000 });

      res.json({ id: user.id, username: user.username, email: user.email });

    } else {

      res.status(401).json({ message: 'Invalid email or password' });

    }

  } catch (error) {

    res.status(500).json({ message: error.message });

  }

};


exports.logoutUser = (req, res) => {

  res.cookie('token', '', { httpOnly: true, expires: new Date(0) });

  res.status(200).json({ message: 'Logged out successfully' });

};


exports.getUserProfile = async (req, res) => {

  try {

    const user = await User.findById(req.user._id).select('-password');

    if (user) {

      res.json(user);

    } else {

      res.status(404).json({ message: 'User not found' });

    }

  } catch (error) {

    res.status(500).json({ message: error.message });

  }

};

server/controllers/taskController.js

Now it’s time to implement the task controller. This controller provides the logic for fetching, creating, updating, and deleting tasks, ensuring that users can only interact with their tasks.

const Task = require('../models/Task');


exports.getTasks = async (req, res) => {

  try {

    const tasks = await Task.find({ user: req.user._id });

    res.status(200).json(tasks);

  } catch (error) {

    res.status(500).json({ message: error.message });

  }

};


exports.createTask = async (req, res) => {

  const { title, description } = req.body;

  if (!title) return res.status(400).json({ message: 'Please add a title' });

  try {

    const task = await Task.create({ title, description, user: req.user._id });

    res.status(201).json(task);

  } catch (error) {

    res.status(500).json({ message: error.message });

  }

};


exports.updateTask = async (req, res) => {

  try {

    const task = await Task.findById(req.params.id);

    if (!task) return res.status(404).json({ message: 'Task not found' });

    if (task.user.toString() !== req.user._id.toString()) return res.status(401).json({ message: 'Not authorized' });


    const updatedTask = await Task.findByIdAndUpdate(req.params.id, req.body, { new: true, runValidators: true });

    res.status(200).json(updatedTask);

  } catch (error) {

    res.status(500).json({ message: error.message });

  }

};


exports.deleteTask = async (req, res) => {

  try {

    const task = await Task.findById(req.params.id);

    if (!task) return res.status(404).json({ message: 'Task not found' });

    if (task.user.toString() !== req.user._id.toString()) return res.status(401).json({ message: 'Not authorized' });


    await Task.deleteOne({ _id: req.params.id });

    res.status(200).json({ message: 'Task removed' });

  } catch (error) {

    res.status(500).json({ message: error.message });

  }

};

server/middleware/authMiddleware.js

To protect private routes, we will create a middleware that verifies the JWT from the request's cookies, ensuring that only authenticated users can access specific endpoints.

const jwt = require('jsonwebtoken');

const User = require('../models/User');

exports.protect = async (req, res, next) => {

  let token;

  if (req.cookies.token) {

    try {

      token = req.cookies.token;

      const decoded = jwt.verify(token, process.env.JWT_SECRET);

      req.user = await User.findById(decoded.id).select('-password');

      next();

    } catch (error) {

      res.status(401).json({ message: 'Not authorized, token failed' });

    }

  } else {

    res.status(401).json({ message: 'Not authorized, no token' });

  }

};

server/middleware/errorMiddleware.js

To handle errors cleanly across our backend, we’ll add global error-handling middleware that can handle 404 Not Found errors and provide a centralized error-handling mechanism for consistent API error responses.

exports.notFound = (req, res, next) => {

  const error = new Error(`Not Found - ${req.originalUrl}`);

  res.status(404);

  next(error);

};


exports.errorHandler = (err, req, res, next) => {

  const statusCode = res.statusCode === 200 ? 500 : res.statusCode;

  res.status(statusCode);

  res.json({

    message: err.message,

    stack: process.env.NODE_ENV === 'production' ? null : err.stack,

  });

};

server/routes/authRoutes.js

Next, let’s define our authentication routes. These endpoints enable user authentication and map HTTP methods to their corresponding controller functions.

const express = require('express');

const { registerUser, loginUser, logoutUser, getUserProfile } = require('../controllers/authController');

const { protect } = require('../middleware/authMiddleware');


const router = express.Router();


router.post('/register', registerUser);

router.post('/login', loginUser);

router.get('/logout', logoutUser);

router.get('/profile', protect, getUserProfile);


module.exports = router;

server/routes/taskRoutes.js

Now we’ll add the routes for task operations. This file defines the API routes for task management, applying the protect middleware to secure all task-related operations.

const express = require('express');

const { getTasks, createTask, updateTask, deleteTask } = require('../controllers/taskController');

const { protect } = require('../middleware/authMiddleware');

const router = express.Router();

router.route('/').get(protect, getTasks).post(protect, createTask);

router.route('/:id').put(protect, updateTask).delete(protect, deleteTask);

module.exports = router;

Frontend Implementation (React)

Dependencies

Now, you’ll need to initialize a new React project and install your essential libraries: Axios for HTTP requests, React Router for navigation, and React Toastify for displaying notifications.

npm install axios react-router-dom react-toastify

client/src/index.js

Let’s start the frontend by setting up the entry point. Here we are rendering the main App component and wrapping it with AuthProvider to provide authentication context globally.

import React from 'react';

import ReactDOM from 'react-dom/client';

import './index.css';

import App from './App';

import { AuthProvider } from './context/AuthContext';


const root = ReactDOM.createRoot(document.getElementById('root'));

root.render(

  <React.StrictMode>

    <AuthProvider>

      <App />

    </AuthProvider>

  </React.StrictMode>

);

client/src/App.js

Next, we’ll define our main App component. This sets up the client-side routing for the application, and defines public and private routes, and includes a navigation bar and toast notification system.

import React from 'react';

import { BrowserRouter as Router, Routes, Route } from 'react-router-dom';

import { ToastContainer } from 'react-toastify';

import 'react-toastify/dist/ReactToastify.css';


import Navbar from './components/Navbar';

import Register from './pages/Register';

import Login from './pages/Login';

import Dashboard from './pages/Dashboard';

import PrivateRoute from './components/PrivateRoute';


function App() {

  return (

    <Router>

      <Navbar />

      <ToastContainer />

      <div className="container">

        <Routes>

          <Route path="/register" element={<Register />} />

          <Route path="/login" element={<Login />} />

          <Route path="/dashboard" element={<PrivateRoute />}>

            <Route index element={<Dashboard />} />

          </Route>

          <Route path="/" element={<h1>Welcome to Task Manager!</h1>} />

        </Routes>

      </div>

    </Router>

  );

}

export default App;

client/src/context/AuthContext.js

We’ll create an authentication context that manages the global authentication state. It provides functions for user login, registration, and logout, and automatically loads user data on component mount.

import React, { createContext, useState, useEffect } from 'react';

import axios from 'axios';

const AuthContext = createContext();

export const AuthProvider = ({ children }) => {

  const [user, setUser] = useState(null);

  const [loading, setLoading] = useState(true);


  useEffect(() => {

    const loadUser = async () => {

      try {

        const res = await axios.get('/api/auth/profile');

        setUser(res.data);

      } catch (err) {

        setUser(null);

      } finally {

        setLoading(false);

      }

    };

    loadUser();

  }, []);


  const login = async (email, password) => {

    try {

      const res = await axios.post('/api/auth/login', { email, password });

      setUser(res.data);

      return true;

    } catch (err) {

      console.error(err.response.data.message);

      return false;

    }

  };


  const register = async (username, email, password) => {

    try {

      const res = await axios.post('/api/auth/register', { username, email, password });

      setUser(res.data);

      return true;

    } catch (err) {

      console.error(err.response.data.message);

      return false;

    }

  };


  const logout = async () => {

    try {

      await axios.get('/api/auth/logout');

      setUser(null);

    } catch (err) {

      console.error(err);

    }

  };


  return (

    <AuthContext.Provider value={{ user, loading, login, register, logout }}>

      {children}

    </AuthContext.Provider>

  );

};


export default AuthContext;

client/src/components/Navbar.js

Here’s a dynamic navigation bar component that dynamically displays links based on the user's authentication status, showing either login/register options or a welcome message and logout button.

import React, { useContext } from 'react';

import { Link } from 'react-router-dom';

import AuthContext from '../context/AuthContext';


const Navbar = () => {

  const { user, logout } = useContext(AuthContext);


  return (

    <nav>

      <h1>Task Manager</h1>

      <div>

        {user ? (

          <>

            <span>Welcome, {user.username}</span>

            <button onClick={logout}>Logout</button>

            <Link to="/dashboard">Dashboard</Link>

          </>

        ) : (

          <>

            <Link to="/login">Login</Link>

            <Link to="/register">Register</Link>

          </>

        )}

      </div>

    </nav>

  );

};


export default Navbar;

client/src/components/PrivateRoute.js

To protect certain pages, we can create a Private Route component. This will be a guard for private routes, ensuring that only authenticated users can access them and redirecting unauthenticated users to the login page.

import React, { useContext } from 'react';

import { Navigate, Outlet } from 'react-router-dom';

import AuthContext from '../context/AuthContext';


const PrivateRoute = () => {

  const { user, loading } = useContext(AuthContext);


  if (loading) {

    return <div>Loading...</div>; // Or a spinner

  }


  return user ? <Outlet /> : <Navigate to="/login" replace />;

};

export default PrivateRoute;

client/src/pages/Register.js

Now, let’s create the Register component, which provides a user registration form, handles input state and form submission, and displays success or error messages using toast notifications.

import React, { useState, useContext } from 'react';

import { useNavigate } from 'react-router-dom';

import { toast } from 'react-toastify';

import AuthContext from '../context/AuthContext';


const Register = () => {

  const [username, setUsername] = useState('');

  const [email, setEmail] = useState('');

  const [password, setPassword] = useState('');

  const { register } = useContext(AuthContext);

  const navigate = useNavigate();


  const handleSubmit = async (e) => {

    e.preventDefault();

    const success = await register(username, email, password);

    if (success) {

      toast.success('Registration successful!');

      navigate('/dashboard');

    } else {

      toast.error('Registration failed. Please try again.');

    }

  };


  return (

    <div>

      <h2>Register</h2>

      <form onSubmit={handleSubmit}>

        <div>

          <label>Username:</label>

          <input type="text" value={username} onChange={(e) => setUsername(e.target.value)} required />

        </div>

        <div>

          <label>Email:</label>

          <input type="email" value={email} onChange={(e) => setEmail(e.target.value)} required />

        </div>

        <div>

          <label>Password:</label>

          <input type="password" value={password} onChange={(e) => setPassword(e.target.value)} required />

        </div>

        <button type="submit">Register</button>

      </form>

    </div>

  );

};


export default Register;

client/src/pages/Login.js

Now, for the login form, it works similarly to the register page but logs users into the system instead. This page manages input fields, handles form submissions, and provides feedback via toast notifications.

import React, { useState, useContext } from 'react';

import { useNavigate } from 'react-router-dom';

import { toast } from 'react-toastify';

import AuthContext from '../context/AuthContext';


const Login = () => {

  const [email, setEmail] = useState('');

  const [password, setPassword] = useState('');

  const { login } = useContext(AuthContext);

  const navigate = useNavigate();


  const handleSubmit = async (e) => {

    e.preventDefault();

    const success = await login(email, password);

    if (success) {

      toast.success('Login successful!');

      navigate('/dashboard');

    } else {

      toast.error('Login failed. Invalid credentials.');

    }

  };


  return (

    <div>

      <h2>Login</h2>

      <form onSubmit={handleSubmit}>

        <div>

          <label>Email:</label>

          <input type="email" value={email} onChange={(e) => setEmail(e.target.value)} required />

        </div>

        <div>

          <label>Password:</label>

          <input type="password" value={password} onChange={(e) => setPassword(e.target.value)} required />

        </div>

        <button type="submit">Login</button>

      </form>

    </div>

  );

};


export default Login;

client/src/pages/Dashboard.js

Finally, we’ll build the Dashboard page. This dashboard component displays a user's tasks, allowing them to create new tasks, mark tasks as complete or incomplete, and delete tasks, with real-time updates.

import React, { useState, useEffect, useContext } from 'react';

import axios from 'axios';

import { toast } from 'react-toastify';

import AuthContext from '../context/AuthContext';


const Dashboard = () => {

  const { user } = useContext(AuthContext);

  const [tasks, setTasks] = useState([]);

  const [newTaskTitle, setNewTaskTitle] = useState('');

  const [newTaskDescription, setNewTaskDescription] = useState('');


  useEffect(() => {

    if (user) {

      fetchTasks();

    }

  }, [user]);


  const fetchTasks = async () => {

    try {

      const res = await axios.get('/api/tasks');

      setTasks(res.data);

    } catch (err) {

      toast.error('Failed to fetch tasks.');

      console.error(err);

    }

  };


  const handleCreateTask = async (e) => {

    e.preventDefault();

    try {

      await axios.post('/api/tasks', { title: newTaskTitle, description: newTaskDescription });

      setNewTaskTitle('');

      setNewTaskDescription('');

      toast.success('Task created successfully!');

      fetchTasks();

    } catch (err) {

      toast.error('Failed to create task.');

      console.error(err);

    }

  };


  const handleUpdateTask = async (id, completed) => {

    try {

      await axios.put(`/api/tasks/${id}`, { completed });

      toast.success('Task updated successfully!');

      fetchTasks();

    } catch (err) {

      toast.error('Failed to update task.');

      console.error(err);

    }

  };


  const handleDeleteTask = async (id) => {

    try {

      await axios.delete(`/api/tasks/${id}`);

      toast.success('Task deleted successfully!');

      fetchTasks();

    } catch (err) {

      toast.error('Failed to delete task.');

      console.error(err);

    }

  };


  return (

    <div>

      <h2>Welcome, {user ? user.username : 'Guest'}!</h2>

      <h3>Your Tasks</h3>

      <form onSubmit={handleCreateTask}>

        <input

          type="text"

          placeholder="New Task Title"

          value={newTaskTitle}

          onChange={(e) => setNewTaskTitle(e.target.value)}

          required

        />

        <input

          type="text"

          placeholder="Description (optional)"

          value={newTaskDescription}

          onChange={(e) => setNewTaskDescription(e.target.value)}

        />

        <button type="submit">Add Task</button>

      </form>

      <ul>

        {tasks.map((task) => (

          <li key={task._id}>

            <span style={{ textDecoration: task.completed ? 'line-through' : 'none' }}>

              {task.title}: {task.description}

            </span>

            <button onClick={() => handleUpdateTask(task._id, !task.completed)}>

              {task.completed ? 'Mark Incomplete' : 'Mark Complete'}

            </button>

            <button onClick={() => handleDeleteTask(task._id)}>Delete</button>

          </li>

        ))}

      </ul>

    </div>

  );

};


export default Dashboard;

Deployment: From Localhost to Live

Deploying a MERN stack application involves deploying the backend API and the frontend React application separately.

Let’s talk about why we do it separately. As you have seen from above, in a MERN stack app, the frontend and backend are separate by design. React handles the UI, while Express and Node handle server logic and API calls. Because they serve different roles, you'll need to deploy them separately.

The backend runs on a Node.js compatible server, which connects to a database such as MongoDB Atlas. The frontend, once it is built, becomes static files that can be hosted from anywhere, from NGINX to hosting platforms like Netlify or Vercel.

This separation provides you with flexibility and improved scalability. Let’s walk through how to deploy each part.

Backend Deployment (Node.js/Express.js)

For backend deployment, platforms like Heroku, Render, or AWS EC2 are common choices. Here, I’ll outline a general approach for a cloud VM on AWS EC2

1. Prepare for Production

To start, set the environment to production and install only the dependencies your app needs to run, optimizing your application's performance. Skipping devDependencies helps reduce its footprint.

export NODE_ENV=production

npm install --production

2. Process Manager (PM2)

Next, we’ll set up a process manager to keep our backend server running reliably. PM2 is a popular tool that handles automatic restarts if your Node.js application crashes, manages multiple app instances, and also helps ensure high availability in production environments.

npm install -g pm2

pm2 start server/app.js --name mern-api

pm2 save

pm2 startup

3. NGINX as a Reverse Proxy

Now that our backend is running with PM2, we need a way to handle incoming web traffic. That’s where NGINX comes in. We'll install NGINX to serve as a high-performance reverse proxy directing incoming web traffic to your Node.js backend and serving static frontend files.

sudo apt update

sudo apt install nginx

Once NGINX is installed, it’s time to configure it (/etc/nginx/sites-available/default or a new config file). We’ll set it up to forward API requests to the backend and serve the React app, acting as the single entry point. You can update the default configuration file or create a new one:

# /etc/nginx/sites-available/default
server {

    listen 80;

    server_name your_domain_or_ip;


    location /api/ {

        proxy_pass http://localhost:5000;

        proxy_http_version 1.1;

        proxy_set_header Upgrade $http_upgrade;

        proxy_set_header Connection 'upgrade';

        proxy_set_header Host $host;

        proxy_cache_bypass $http_upgrade;

    }


    location / {

        root /var/www/my-mern-app/client/build; # Path to your React build folder

        try_files $uri /index.html;

    }

}

With the NGINX configuration created, we’ll enable it and restart the service to apply the changes, making your application go live:

sudo ln -s /etc/nginx/sites-available/default /etc/nginx/sites-enabled/

sudo systemctl restart nginx

4. HTTPS with Certbot (Let's Encrypt)

To secure your app with HTTPS, we can install Certbot and use it to automatically obtain and configure a free SSL/TLS certificate from Let’s Encrypt, enabling secure HTTPS connections for your domain.

sudo snap install --classic certbot

sudo certbot --nginx -d your_domain_or_ip

Frontend Deployment (React)

With the backend deployed, let’s move to the frontend. For the React frontend, we’ll build the application and serve the static files via NGINX (as shown above) or a dedicated static site hosted on platforms like Netlify, Vercel, or AWS S3 + CloudFront.

Build the React App

This command compiles and optimizes your React application into a build folder containing static assets, ready for efficient deployment to any web server or static hosting service.

cd client

npm run build

Database Deployment (MongoDB Atlas)

For production, we’ll use a managed MongoDB service like MongoDB Atlas. It handles replication, sharding, and backups, simplifying database management significantly.

Create a Cluster on MongoDB Atlas

• Sign up/Log in to MongoDB Atlas.

• Create a new cluster (choose a cloud provider and region).

• Set up a database user with appropriate permissions.

• Configure network access (allow connections from your server's IP address).

• Get your connection string and update MONGO_URI in your server/.env file.

1. .env Configuration Example

After creating the cluster and user in MongoDB Atlas, you’ll receive a connection string. You need to update your .env file with it

# server/.env
MONGO_URI=mongodb+srv://yourUser:yourPassword@cluster0.mongodb.net/yourDBName
JWT_SECRET=your_secret_jwt_key
NODE_ENV=production

2. Connect to MongoDB in app.js

Next, in the server/app.js file, make sure you're using the connection string from the environment variable:

const mongoose = require('mongoose');
const dotenv = require('dotenv');
dotenv.config();

mongoose.connect(process.env.MONGO_URI)
  .then(() => console.log('MongoDB connected!'))
  .catch((err) => console.error('Connection error:', err));

Other Deployment Options

While this article drives you through manual deployment with EC2 and NGINX, other platforms can simplify the process:

• Render, Railway, and Heroku offer easy full-stack deployment with GitHub integration.

• Vercel and Netlify are ideal for hosting the React frontend.

• You may consider using Docker to maintain consistent environments across development and production.

• For CI/CD, Linting, Testing, & Deployment can be automated on every push using tools like GitHub Actions

There is no right or wrong choice here. Select the setup that best suits your project’s scale, team experience, and desired level of control.

Security Best Practices: Fortifying Your Application

Security is paramount. You can implement these best practices to protect your MERN application.

Setup Input Validation and Sanitization

Always validate and sanitize input on the server side. You can use libraries like Joi or Zod to make this process easier.

Example with Joi:

To validate and sanitize incoming data on the server, we will utilize Joi, a powerful library for defining schemas and enforcing input rules.

npm install joi

Now that we’ve installed Joi, we will use it to define strict validation rules for user registration and login inputs. This ensures data quality and prevents common injection attacks.

// server/validators/authValidator.js

const Joi = require('joi');


const registerSchema = Joi.object({

  username: Joi.string().min(3).max(30).required(),

  email: Joi.string().email().required(),

  password: Joi.string().min(6).required(),

});


const loginSchema = Joi.object({

  email: Joi.string().email().required(),

  password: Joi.string().required(),

});


module.exports = { registerSchema, loginSchema };

Next, we’ll integrate these schemas directly into our authentication controller to automatically validate incoming request bodies against predefined schemas.

// server/controllers/authController.js (snippet)

const { registerSchema, loginSchema } = require('../validators/authValidator');


exports.registerUser = async (req, res) => {

  const { error } = registerSchema.validate(req.body);

  if (error) return res.status(400).json({ message: error.details[0].message });

  // ... rest of the registration logic

};


exports.loginUser = async (req, res) => {

  const { error } = loginSchema.validate(req.body);

  if (error) return res.status(400).json({ message: error.details[0].message });

  // ... rest of the login logic

};

Add Authentication and Authorization

You can use JWTs for authentication and implement middleware for protected routes.

JWT Implementation (covered in authController.js and authMiddleware.js above)

Key aspects:

• HttpOnly Cookies: Store JWTs in HttpOnly cookies to prevent client-side JavaScript access, mitigating XSS attacks.

• Secure Flag: Use secure: true in production to ensure cookies are only sent over HTTPS.

These practices ensure that authentication tokens are securely transmitted and stored, protecting against common web vulnerabilities like Cross-Site Scripting (XSS).

Implement Rate Limiting

To protect our API from abuse and malicious intent, we will implement basic rate limiting. This helps protect against brute-force login attempts and DDoS attacks.

Installation

We will install express-rate-limit package for it

npm install express-rate-limit

server/app.js (snippet)

Once it is installed, let’s configure the rate limiter and apply it to all incoming requests. This ensures that no single IP can overwhelm your server with repeated calls. The following middleware limits each IP address to 200 requests within a 15-minute window.

const rateLimit = require('express-rate-limit');

const limiter = rateLimit({

  windowMs: 15 * 60 * 1000, // 15 minutes

  max: 200, // Limit each IP to 200 requests per windowMs

  message: 'Too many requests from this IP, please try again after 15 minutes',

});

app.use(limiter); // Apply to all requests

Setup CORS Configuration (Cross-Origin Resource Sharing)

Next, we move our focus to enable secure communication between your frontend and backend. By default, all browsers block cross-origin requests, so we need to configure CORS (Cross-Origin Resource Sharing) to permit the React app to communicate with the Express API.

Installation

npm install cors

server/app.js (snippet)

Once installed, we can configure CORS for our Express application, specifying allowed origins and enabling credential sharing for secure cross-origin requests. Remember to replace the origin with your actual production URL when deploying.

const cors = require('cors');

app.use(cors({

  origin: 'http://localhost:3000', // Replace with your frontend URL in production

  credentials: true,

}));

Use Environment Variables

To keep sensitive information secure and out of your codebase, we will use environment variables. This allows us to efficiently manage secrets, such as database connection strings and JWT keys, without hardcoding them or including them in the source code.

Create a .env file in your server/ directory:

.env (example)

This .env file stores sensitive configuration details like database connection strings and API keys

MONGO_URI=your_mongodb_connection_string

JWT_SECRET=your_super_secret_jwt_key

NODE_ENV=production

Monitoring and Logging with Winston and Morgan

Once the application is live, it's critical to monitor the behavior and catch issues promptly. Monitoring and logging help you measure performance, find bugs, and keep a log of all server activity.

We’ll use Morgan for logging HTTP requests and Winston for more general-purpose application logging.

Installation

We will install Morgan for logging HTTP requests and Winston for comprehensive and customizable application logging.

npm install morgan winston

server/config/logger.js

Next, let’s configure Winston to handle our application logs. This will output logs to the console by default, with options to enable file-based logging for errors and general information.

const winston = require('winston');

const logger = winston.createLogger({

  level: 'info',

  format: winston.format.combine(

    winston.format.timestamp(),

    winston.format.json()

  ),

  transports: [

    new winston.transports.Console(),

    // new winston.transports.File({ filename: 'error.log', level: 'error' }),

    // new winston.transports.File({ filename: 'combined.log', level: 'info' }),

  ],

});

module.exports = logger;

server/app.js (snippet)

With Winston and Morgan set up, now let’s integrate them into our app.js file. We’ll use Morgan for request logging during development and replace standard console.log calls with Winston logs for structured and configurable application logging.

const morgan = require('morgan');

const logger = require('./config/logger');

if (process.env.NODE_ENV === 'development') {

  app.use(morgan('dev'));

}

// Replace console.log with logger.info for database connection

mongoose.connect(process.env.MONGO_URI)

  .then(() => logger.info('MongoDB connected!'))

  .catch(err => logger.error('MongoDB connection error:', err));


// Replace console.log in app.listen

app.listen(PORT, () => {

  logger.info(`Server running on port ${PORT}`);

});

Frontend Error Monitoring (Sentry)

To monitor errors in the frontend, we’ll integrate Sentry. It’s a fantastic tool for tracking exceptions and performance issues in real time. It helps us capture and report client-side errors.

Installation

npm install @sentry/react @sentry/tracing

client/src/index.js (snippet)

After installation, let’s initialize Sentry in the React application so that it can automatically capture errors and performance data. We’ll add this to our index.js file.

import * as Sentry from '@sentry/react';

import { BrowserTracing } from '@sentry/tracing';


Sentry.init({

  dsn: "YOUR_SENTRY_DSN", // Replace with your Sentry DSN

  integrations: [new BrowserTracing()],

  tracesSampleRate: 1.0,

  environment: process.env.NODE_ENV,

});

And that’s it! Congratulations on building and deploying a full-stack MERN app.

Conclusion

This article provided a code-first walkthrough of building, securing, and deploying a MERN stack application. By focusing on practical code examples and essential configurations, you now have a solid foundation for your MERN projects.

Remember, continuous learning and adaptation are key in the ever-evolving world of web development. Happy coding!

A buffer overflow happens when a program writes more data into a buffer than it was allocated, leading to memory corruption, crashes, or even security vulnerabilities. A buffer corruption occurs when unintended modifications overwrite unread data or modify memory in unexpected ways.

In safety-critical systems like cars, medical devices, and spacecraft, buffer overflows can cause life-threatening failures. Unlike simple software bugs, buffer overflows are unpredictable and depend on the state of the system, making them difficult to diagnose and debug.

To prevent these issues, it's important to understand how buffer overflows and corruptions occur, and how to detect and fix them.

Article Scope

In this article, you will learn:

1. What buffers, buffer overflows, and corruptions are. I’ll give you a beginner-friendly explanation with real-world examples.

2. How to debug buffer overflows. You’ll learn how to use tools like GDB, LLDB, and memory maps to find memory corruption.

3. How to prevent buffer overflows. We’ll cover some best practices like input validation, safe memory handling, and defensive programming.

I’ll also show you some hands-on code examples – simple C programs that demonstrate buffer overflow issues and how to fix them.

What this article doesn’t cover:

1. Security exploits and hacking techniques. We’ll focus on preventing accidental overflows, not hacking-related buffer overflows.

2. Operating system-specific issues. This guide is for embedded systems, not general-purpose computers or servers.

3. Advanced RTOS memory management. While we discuss interrupt-driven overflows, we won’t dive deep into real-time operating system (RTOS) concepts.

Now that you know what this article covers (and what it doesn’t), let’s go over the skills that will help you get the most out of it.

Prerequisites

This article is designed for developers who have some experience with C programming and want to understand how to debug and prevent buffer overflows in embedded systems. Still, beginners can follow along, as I’ll explain key concepts in a clear and structured way.

Before reading, it helps if you know:

1. Basic C programming.

2. How memory works – the difference between stack, heap, and global variables.

3. Basic debugging concepts – if you’ve used a debugger like GDB or LLDB, that’s a plus, but not required.

4. What embedded systems are – a basic idea of how microcontrollers store and manage memory.

Even if you’re not familiar with these topics, this guide will walk you through them in an easy-to-understand way.

Before you dive into buffer overflows, debugging, and prevention, let’s take a step back and understand what a buffer is and why it’s important in embedded systems. Buffers play a crucial role in managing data flow between hardware and software but when handled incorrectly, they can lead to serious software failures.

Table of Contents

• What is a Buffer, and How Does it Work?

• What is a Buffer Overflow?

• Common Causes of Buffer Overflows and Corruption

• Consequences of Buffer Overflows

• How to Debug Buffer Overflows

• How to Prevent Buffer Overflows

• Conclusion

What is a Buffer, and How Does it Work?

A buffer is a contiguous block of memory used to temporarily store data before it is processed. Buffers are commonly used in two scenarios:

1. Data accumulation: When the system needs to collect a certain amount of data before processing.

2. Rate matching: When the data producer generates data faster than the data consumer can process it.

Buffers are typically implemented as arrays in C, where elements are indexed from 0 to N-1 (where N is the buffer size).

Let’s look at an example of a buffer in a sensor system.

Consider a system with a sensor task that generates data at 400 Hz (400 samples per second or 1 sample every 2.5 ms). But the data processor (consumer) operates at only 100 Hz (100 samples per second or 1 sample every 10 ms). Since the consumer task is slower than the producer, we need a buffer to store incoming data until it is processed.

To determine the buffer size, we calculate:

Buffer Size = Time to consume 1 sample / Time to generate 1 sample = 10 ms/ 2.5 ms = 4

This means the buffer must hold at least 4 samples at a time to avoid data loss.

Once the buffer reaches capacity, there are several strategies to decide which data gets passed to the consumer task:

1. Max/min sampling: Use the maximum or minimum value in the buffer.

2. Averaging: Compute the average of all values in the buffer.

3. Random access: Pick a sample from a specific location (for example, the most recent or the first).

In real-world applications, it’s beneficial to use circular buffers or double buffering to prevent data corruption.

• Circular buffer approach: A circular buffer (also called a ring buffer) continuously wraps around when it reaches the end, ensuring old data is overwritten safely without exceeding memory boundaries. The buffer size should be multiplied by 2 (4 × 2 = 8) to hold 8 samples. This allows the consumer task to process 4 samples while the next 4 samples are being filled, preventing data overwrites.

• Double buffer approach: Double buffering is useful when data loss is unacceptable. It allows continuous data capture while the processor is busy handling previous data. A second buffer of the same size is added. When the first buffer is full, the write pointer switches to the second buffer, allowing the consumer task to process data from the first buffer while the second buffer is being filled. This prevents data overwrites and ensures a continuous data flow.

Buffers help manage data efficiently, but what happens when they are mismanaged? This is where buffer overflows and corruptions come into play.

What is a Buffer Overflow?

A buffer overflow occurs when a program writes more data into a buffer than it was allocated, causing unintended memory corruption. This can lead to unpredictable behavior, ranging from minor bugs to critical system failures.

To understand buffer overflow, let's use a simple analogy. Imagine a jug with a tap near the bottom. The jug represents a buffer, while the tap controls how much liquid (data) is consumed.

The jug is designed to hold a fixed amount of liquid. As long as water flows into the jug at the same rate or slower than it flows out, everything works fine. But if water flows in faster than it flows out, the jug will eventually overflow.

Similarly, in software, if data enters a buffer faster than it is processed, it exceeds the allocated memory space, causing a buffer overflow. In the case of a circular buffer, this can cause the write pointer to wrap around and overwrite unread data, leading to buffer corruption.

Buffer Overflows in Software

Unlike the jug, where water simply spills over, a buffer overflow in software overwrites adjacent memory locations. This can cause a variety of hard-to-diagnose issues, including:

1. Corrupting other data stored nearby.

2. Altering program execution, leading to crashes.

3. Security vulnerabilities, where attackers exploit overflows to inject malicious code.

When a buffer overflow occurs, data can overwrite variables, function pointers, or even return addresses, depending on where the buffer is allocated.

Buffer overflows can occur in different memory regions:

1. Buffer overflows in global/static memory (.bss / .data sections)

   • These occur when global or static variables exceed their allocated size.

   • The overflow can corrupt adjacent variables, leading to unexpected behavior in other modules.

   • Debugging is easier because memory addresses are fixed at compile time unless the compiler optimizes them. Map files provide a memory layout of variables during the compilation and linking.

2. Stack-based buffer overflow (more predictable, easier to debug):

   • Happens when a buffer is allocated in the stack (for example, local variables inside functions).

   • Overflowing the stack can affect adjacent local variables or return addresses, potentially crashing the program.

   • In embedded systems with small stack sizes, this often leads to a crash or execution of unintended code.

3. Heap-based buffer overflow (harder to debug):

   • Happens when a buffer is dynamically allocated in the heap (for example, using malloc() in C).

   • Overflowing a heap buffer can corrupt adjacent dynamically allocated objects or heap management structures.

   • Debugging is harder because heap memory is allocated dynamically at runtime, causing memory locations to vary.

Buffer Overflow vs Buffer Corruption

Buffer overflow and buffer corruption are of course related, but refer to different situations.

A buffer overflow happens when data is written beyond the allocated buffer size, leading to memory corruption, unpredictable behavior, or system crashes.

A buffer corruption happens when unintended data modifications result in unexpected software failures, even if the write remains within buffer boundaries.

Both issues typically result from poor write pointer management, lack of boundary checks, and unexpected system behavior.

Now that we've covered what a buffer overflow is and how it can overwrite memory, let’s take a closer look at how these issues affect embedded systems.

In the next section, we’ll explore how buffer overflows and corruption happen in real-world embedded systems and break down common causes, including pointer mismanagement and boundary violations.

Common Causes of Buffer Overflows and Corruption

Embedded systems use buffers to store data from sensors, communication interfaces (like UART (Universal Asynchronous Receiver-Transmitter), SPI (Serial Peripheral Interface), I2C (Inter-integrated Circuit), and real-time tasks. These buffers are often statically allocated to avoid memory fragmentation, and many implementations use circular (ring) buffers to efficiently handle continuous data streams.

Here are three common scenarios where buffer overflows or corruptions occur in embedded systems:

Writing Data Larger Than the Available Space

Issue: The software writes incoming data to the buffer without checking if there is enough space.

Example: Imagine a 100-byte buffer to store sensor data. The buffer receives variable-sized packets. If an incoming packet is larger than the remaining space, it will overwrite adjacent memory, leading to corruption.

So why does this happen?

• Some embedded designs increment the write pointer after copying data, making it too late to prevent overflow.

• Many low-level memory functions (memcpy, strcpy, etc.) do not check buffer boundaries, leading to unintended writes.

• Without proper bound checking, a large write can exceed the buffer size and corrupt nearby memory.

Here’s a code sample to demonstrate buffer overflow in a .bss / .data section:

  #include <stdint.h>
  #include <stdio.h>
  #include <string.h>

  #define BUFFER_SIZE 300

  static uint16_t sample_count = 0;
  static uint8_t buffer[BUFFER_SIZE] = {0};

  // Function to simulate a buffer overflow scenario
  void updateBufferWithData(uint8_t *data, uint16_t size)
  {
      // Simulating a buffer overflow: No boundary check!
      printf("Attempting to write %d bytes at position %d...\n", size, sample_count);

      // Deliberate buffer overflow for demonstration
      if (sample_count + size > BUFFER_SIZE)
      {
          printf("WARNING: Buffer Overflow Occurred! Writing beyond allocated memory!\n");
      }

      // Copy data (unsafe, can cause overflow)
      memcpy(&buffer[sample_count], data, size);

      // Increment sample count (incorrectly, leading to wraparound issues)
      sample_count += size;
  }

  int main()
  {   
      // Save 1 byte to buffer
      uint8_t data_to_buffer = 10;
      updateBufferWithData(&data_to_buffer, 1);

      // Save an array of 20 bytes to buffer
      uint8_t data_to_buffer_1[20] = {5};
      updateBufferWithData(data_to_buffer_1, sizeof(data_to_buffer_1));

      // Intentional buffer overflow: Save an array of 50 x 8 bytes (400 bytes)
      uint64_t data_to_buffer_2[50] = {7};
      updateBufferWithData((uint8_t*)data_to_buffer_2, sizeof(data_to_buffer_2));

      return 0;
  }

Interrupt-Driven Overflows (Real-time Systems)

Issue: The interrupt service routine (ISR) may write data faster than the main task can process, leading to buffer corruption or buffer overflow if the write pointer is not properly managed.

Example: Imagine a sensor ISR that writes incoming data into a buffer every time a new reading arrives. Meanwhile, a low-priority processing task reads and processes the data.

What can go wrong?

• If the ISR triggers too frequently (due to a misbehaving sensor or high interrupt priority), the buffer may fill up faster than the processing task can keep up.

• This can result in one of two failures:

  1. Buffer Corruption: The ISR overwrites unread data, leading to loss of information.

  2. Buffer Overflow: The ISR exceeds buffer boundaries, causing memory corruption or system crashes.

So why does this happen?

• In real-time embedded systems, ISR execution preempts lower-priority tasks.

• If the processing task doesn't not get enough CPU time, the buffer may become overwritten or overflow beyond its allocated scope.

System State Changes & Buffer Corruption

Issue: The system may unexpectedly reset, enter low-power mode, or changes operating state, leaving the buffer write pointers in an inconsistent state. This can result in buffer corruption (stale or incorrect data) or buffer overflow (writing past the buffer’s limits.

Example Scenarios:

1. Low-power wake-up issue (Buffer Overflow risk): Some embedded systems enter deep sleep to conserve energy. Upon waking up, if the buffer write pointer is not correctly reinitialized, it may point outside buffer boundaries, leading to buffer overflow and unintended memory corruption.

2. Unexpected mode transitions: If a sensor task is writing data and the system suddenly switches modes, the buffer states and pointers may not be cleaned up. The next time the sensor task runs, it may continue writing without clearing previous data. This can cause undefined behavior due to presence of stale data.

Now that you understand how buffer overflows and corruptions happen, let’s examine their consequences in embedded systems ranging from incorrect sensor readings to complete system failures, making debugging and prevention critical.

Consequences of Buffer Overflows

Buffer overflows can be catastrophic in embedded systems, leading to system crashes, data corruption, and unpredictable behavior. Unlike general-purpose computers, many embedded devices lack memory protection, making them particularly vulnerable to buffer overflows.

A buffer overflow can corrupt two critical types of memory:

1. Data Variables Corruption

A buffer overflow can overwrite data variables, corrupting the inputs for other software modules. This can cause unexpected behavior or even system crashes if critical parameters are modified.

For example, a buffer overflow could accidentally overwrite a sensor calibration value stored in memory. As a result, the system would start using incorrect sensor readings, leading to faulty operation and potentially unsafe conditions.

2. Function Pointer Corruption

In embedded systems, function pointers are often used for interrupt handlers, callback functions, and RTOS task scheduling. If a buffer overflow corrupts a function pointer, the system may execute unintended instructions, leading to a crash or unexpected behavior.

As an example, a function pointer controlling motor speed regulation could be overwritten. Instead of executing the correct function, the system would jump to a random memory address, causing a system fault or erratic motor behavior.

Buffer overflows are among the hardest bugs to identify and fix because their effects depend on which data is corrupted and the values it contains. A buffer overflow can affect memory in different ways:

• If a buffer overflow corrupts unused memory, the system may seem fine during testing, making the issue harder to detect.

• if a buffer overflow alters critical data variables, it can cause hidden logic errors that cause unpredictable behavior.

• If a buffer overflow corrupts function pointers, it may crash immediately, making the problem easier to identify.

During development, if tests focus only on detecting crashes, they may overlook silent memory corruption caused by a buffer overflow. In real-world deployments, new use cases not covered in testing can trigger previously undetected buffer overflow issues, leading to unpredictable failures.

Buffer overflows can cause a chain reaction, where one overflow leads to another overflow or buffer corruption, resulting in widespread system failures. So how does this happen?

1. A buffer overflow corrupts a critical variable (for example, a timer interval).

2. The corrupted variable disrupts another module (for example, triggers the timer interrupt too frequently, causing it to push more data into a buffer than intended.).

3. This increased interrupt frequency forces a sensor task to write data faster than intended, eventually causing another buffer overflow or corruption by overwriting unread data.

This chain reaction can spread across multiple software modules, making debugging nearly impossible. In real-word applications, buffer overflows in embedded systems can be life-threatening:

• In cars: A buffer overflow in an ECU (Electronic Control Unit) could cause brake failure or unintended acceleration.

• In a spacecraft: A memory corruption issue could disable navigation systems, leading to mission failure.

Now that we’ve seen how buffer overflows can corrupt memory, disrupt system behavior, and even cause critical failures, the next step is understanding how to detect and fix them before they lead to serious issues.

How to Debug Buffer Overflows

Debugging buffer overflows in embedded systems can be complex, as their effects range from immediate crashes to silent data corruption, making them difficult to trace. A buffer overflow can cause either:

1. A system crash, which is easier to detect since it halts execution or forces a system reboot.

2. Unexpected behavior, which is much harder to debug as it requires tracing how corrupted data affects different modules.

This section focuses on embedded system debugging techniques using memory map files, debuggers (GDB/LLDB), and a structured debugging approach. Let’s look into the debuggers and memory map files.

Memory Map File (.map file)

A memory map file is generated during the linking process. It provides a memory layout of global/static variables, function addresses, and heap/stack locations. It provides a memory layout of Flash and RAM, including:

• Text section (.text): Stores executable code.

• Read-only section (.rodata): Stores constants and string literals.

• BSS section (.bss): Stores uninitialized global and static variables.

• Data section (.data): Stores initialized global and static variables.

• Heap and stack locations, depending on the linker script.

If a buffer overflow corrupts a global variable, the .map file can identify nearby variables that may also be affected, provided the compiler has not optimized the memory allocation. Similarly, if a function pointer is corrupted, the .map file can reveal where it was stored in memory.

Debuggers (GDB & LLDB)

Debugging tools like GDB (GNU Debugger) and LLDB (LLVM Debugger) allow:

• Controlling execution (breakpoints, stepping through code).

• Inspecting variable values and memory addresses.

• Getting backtraces (viewing function calls before a crash).

• Extracting core dumps from microcontrollers for post-mortem analysis.

If the system halts on a crash, a backtrace (bt command in GDB) can reveal which function was executing before failure. If the overflow affects a heap-allocated variable, GDB can inspect heap memory usage to detect corruption.

The Debugging Process

Now, let’s go through a step-by-step debugging process to identify and fix buffer overflows. Once a crash or unexpected behavior occurs, follow these techniques to trace the root cause:

Step 1: Identify the misbehaving module

If the system crashes, use GDB or LLDB backtrace (bt command) to locate the last executed function. If the system behaves unexpectedly, determine which software module controls the affected functionality.

Step 2: Analyze inputs and outputs of the module

Every function or module has inputs and outputs. Create a truth table listing expected outputs for all possible inputs. Check if the unexpected behavior matches any undefined input combination, which may indicate corruption.

Step 3: Locate memory corruption using address analysis

If a variable shows incorrect values, determine its physical memory location. Depending on where the variable is stored:

1. Global/static variables (.bss / .data): Look up the memory map file for nearby buffers.

2. Heap variables: Snapshot heap allocations using GDB.

   Here’s an example of using GDB to find corrupted variables:

    (gdb) print &my_variable  # Get memory address of the variable
    $1 = (int *) 0x20001000
    (gdb) x/10x 0x20001000   # Examine memory near this address, Display 10 memory words in hexadecimal format starting from 0x20001000
   

Step 4: Identify the overflowing buffer

If a buffer is located just before the corrupted variable, inspect its usage in the code. Review all possible code paths that write to the buffer. Check if any design limitations could cause an overflow under a specific use cases.

Step 5: Fix the root cause

If the buffer overflow happened due to missing bounds checks, add proper input validation to prevent it. Buffer design should enforce strict memory limits. The module should implement strict boundary checks for all inputs and maintain a consistent state.

In addition to GDB/LLDB, you can also use techniques like hardware tracing and fault injection to simulate buffer overflows and observe system behavior in real-time.

While debugging helps identify and fix buffer overflows, prevention is always the best approach. Let’s explore techniques that can help avoid buffer overflows altogether.

How to Prevent Buffer Overflows

You can often prevent buffer overflows through good software design, defensive programming, hardware protections, and rigorous testing. Embedded systems, unlike general-purpose computers, often lack memory protection mechanisms, which means that buffer overflow prevention critical for system reliability and security.

Here are some key techniques to help prevent buffer overflows:

Defensive Programming

Defensive programming helps minimize buffer overflow risks by ensuring all inputs are validated and unexpected conditions are handled safely.

First, it’s crucial to validate input size before writing to a buffer. Always check the write index by adding the size of data to be written prior to writing data to make sure more data is not written than the available buffer space.

Then you’ll want to make sure you have proper error handling and fail-safe mechanisms in place. If an input is invalid, halt execution, log the error, or switch to a safe state. Also, functions should indicate success/failure with helpful error codes to prevent misuse.

Sample Code:

   #include <stdint.h>
   #include <string.h>
   #include <stdbool.h>
   #include <stdio.h>

   #define BUFFER_SIZE 300

   static uint16_t sample_count = 0;
   static uint8_t buffer[BUFFER_SIZE] = {0};

   typedef enum
   {
       SUCCESS = 0,
       NOT_ENOUGH_SPACE = 1,
       DATA_IS_INVALID = 2,
   } buffer_err_code_e;


   buffer_err_code_e updateBufferWithData(uint8_t *data, uint16_t size)
   {
       if (data == NULL || size == 0 || size > BUFFER_SIZE)  
       {
           return DATA_IS_INVALID; // Invalid input size
       }

       uint16_t available_space = BUFFER_SIZE - sample_count;
       bool can_write = (available_space >= size) ? true : false;

       if (!can_write)  
       {
           return NOT_ENOUGH_SPACE;
       }

       // Copy data safely
       memcpy(&buffer[sample_count], data, size);
       sample_count += size;

       return SUCCESS;
   }

   int main()
   {   
       buffer_err_code_e ret;

       // Save 1 byte to buffer
       uint8_t data_to_buffer = 10;
       ret = updateBufferWithData(&data_to_buffer, sizeof(data_to_buffer));
       if (ret)  
       {
           printf("Buffer update didn't succeed, Err:%d\n", ret);
       }

       // Save an array of 20 bytes to buffer
       uint8_t data_to_buffer_1[20] = {5};
       ret = updateBufferWithData(data_to_buffer_1, sizeof(data_to_buffer_1));
       if (ret)  
       {
           printf("Buffer update didn't succeed, Err:%d\n", ret);
       }

       // Save an array of 50 x 8 bytes, Intentional buffer overflow
       uint64_t data_to_buffer_2[50] = {7};
       ret = updateBufferWithData((uint8_t*)data_to_buffer_2, sizeof(data_to_buffer_2));  
       if (ret)  
       {
           printf("Buffer update didn't succeed, Err:%d\n", ret);
       }

       return 0;
   }

Choosing the Right Buffer Design And Size

Some buffer designs handle overflow better than others. Choosing the correct buffer type and size for the application reduces the risk of corruption.

• Circular Buffers (Ring Buffers) prevent out-of-bounds writes by wrapping around. They overwrite the oldest data instead of corrupting memory. These are useful for real-time streaming data (for example, UART, sensor readings). This approach is ideal for applications where data loss is unacceptable.

• Ping-Pong Buffers (Double Buffers) use two buffers. One buffer fills up with data. Then, once it’s full, it switches to the second buffer while the first one is processed. This approach is beneficial for application that have strict requirements on no data loss. The buffer design should be based on the speed of write and read tasks.

Hardware Protection

Memory Protection Unit (MPU)

An MPU (Memory Protection Unit) helps detect unauthorized memory accesses, including buffer overflows, by restricting which regions of memory can be written to. It prevents buffer overflows from modifying critical memory regions and triggers a MemManage Fault if a process attemps to write outside an allowed region.

But keep in mind that, an MPU does not prevent buffer overflows – it only detects and stops execution when they occur. Not all microcontrollers have an MPU, and some low-end MCUs lack hardware protection, making software-based safeguards even more critical.

Modern C compilers provide several flags to identify memory errors at compile-time:

1. -Wall -Wextra: Enables useful warnings

2. -Warray-bounds: Detects out-of-bounds array access when the array size is known at compile-time

3. -Wstringop-overflow: Warns about possible overflows in string functions like memcpy and strcpy.

Testing and Validation

Testing helps detect buffer overflows before deployment, reducing the risk of field failures. Unit testing each function independently with valid inputs, boundary cases, and invalid inputs helps detect buffer-related issues early. Automated testing involves feeding random and invalid inputs into the system to uncover crashes and unexpected behavior. Static Analysis Tools like Coverity, Clang Static Analyzer help detect buffer overflows before runtime. Run real-world inputs on embedded hardware to detect issues.

Now that we've explored how to identify, debug, and prevent buffer overflows, it’s clear that these vulnerabilities pose a significant threat to embedded systems. From silent data corruption to catastrophic system failures, the consequences can be severe.

But with the right debugging tools, systematic analysis, and preventive techniques, you can effectively either prevent or mitigate buffer overflows in your systems.

Conclusion

Buffer overflows and corruption are major challenges in embedded systems, leading to crashes, unpredictable behavior, and security risks. Debugging these issues is difficult because their symptoms vary based on system state, requiring systematic analysis using memory map files, GDB/LLDB, and structured debugging approaches.

In this article, we explored:

• The causes and consequences of buffer overflows and corruptions

• How to debug buffer overflows using memory analysis and debugging tools

• Best practices for prevention

Buffer overflow prevention requires a multi-layered approach:

1. Follow a structured software design process to identify risks early.

2. Apply defensive programming principles to validate inputs and handle errors gracefully.

3. Use hardware-based protections like MPUs where available.

4. Enable compiler flags that help identify memory errors.

5. Test extensively, unit testing, automated testing, and code reviews help catch vulnerabilities early.

By implementing these best practices, you can minimize the risk of buffer overflows in embedded systems, improving reliability and security.

In embedded systems, where reliability and safety are critical, preventing buffer overflows is not just a best practice, it is a necessity. A single buffer overflow can compromise an entire system. Defensive programming, rigorous testing, and hardware protections are essential for building secure and robust embedded applications.

It’s not just about learning a programming language and typing out code to build software. There’s a lot more to it. And one of the most confusing (and often frustrating) topics for developers is clean code.

So, what is clean code?

Simply put, it’s about writing code that’s so clear and well-organized that neither you nor anyone else will get frustrated trying to understand it six months later.

Think of clean code as the programming equivalent of great design — it’s functional, beautiful, and easy to work with.

And today, I won’t spend a lot of time explaining why clean code is important — you probably already know that. Instead, I’ll get straight to the point and share seven powerful hacks to help you write cleaner, better code.

Table of Contents

• 1. Write Code Like You’re Explaining it to a 5-Year Old

• 2. Use AI Tools (or an AI Code Reviewer)

• 3. Get Rid of Unnecessary Comments

• 4. Follow the DRY Principle

• 5. Fix Your Code Formatting & Follow a Consistent Style

• 6. Don’t Let Your Functions Do Too Much

• 7. Organize Your Files and Folders Properly

• Wrapping Up

1. Write Code Like You’re Explaining it to a 5-Year Old

Let me be honest — if you are writing exceedingly clever code that your teammates or someone else can’t easily read, it won’t be helpful to anyone.

You need to write code so simple that anyone, including someone who just opened the file for the first time, can easily go through it.

For example, if your variable names look like this:

let x = y + z;

This isn’t helpful. No one will know what x, y, and z mean — not even you, three weeks later.

Variables should describe what they hold. Think of them as self-documenting comments. Here’s a better example:

let totalPrice = productPrice + shippingCost;

This simple best practice can be applied even when writing functions, comments, and more.

Here’s an example of hard to understand code:

function calc(itm) {
 let t = 0;
 for (let i = 0; i < itm.length; i++) {
 t += itm[i].p;
 }
 return t;
}

You see, it doesn’t give you a proper idea about the function other than the logic.

Instead, try to write it like this:

function calculateTotalPrice(cartItems) {
    let totalPrice = 0;
    for (let i = 0; i < cartItems.length; i++) {
        totalPrice += cartItems[i].price;
    }
    return totalPrice;
}

Now it’s clear just from looking at the code what’s going on.

2. Use AI Tools (or an AI Code Reviewer)

AI is evolving quickly and is being used in almost every industry.

Well, as a developer, you can use AI to help you write clean and readable code — all thanks to AI tools like ChatGPT, Claude, and GitHub Copilot.

For starters, you can copy and paste your code into an LLM and ask it to review your code.

Here’s an example of a request I made to ChatGPT:

And here’s what ChatGPT recommended:

It even provided me with an improved version of the code. Here it is as follows:

Along with that, you can also use AI-powered code reviewers like CodeRabbit AI, which integrates with your pull requests to offer automated code reviews, walkthroughs, and more.

In simple terms, when you install CodeRabbit AI, add it to your pull request, and then create a pull request, CodeRabbit AI provides you with summaries, code reviews, walkthroughs, and more.

Here’s an example from an open-source repository “minefield” of a summary generated by CodeRabbit AI:

In the above examples, CodeRabbit AI simply goes through the code and provides a great summary highlighting the new features, bug fixes, and unit tests added via a pull request.

If you want to learn more, here’s a quickstart guide that provides more info on how to get started and use CodeRabbit AI.

Note that, AI tools can be a great help in improving your code, but they should never replace your own thinking.

When AI suggests changes, always ask yourself: Does this actually make sense?

After all, AI isn’t perfect—it can generate incorrect code. It might also miss important details that only a human can fully understand.

So instead of blindly accepting AI’s suggestions, take a moment to understand why they were made.

Remember, the goal is to use AI to speed up your workflow, catch errors, and more—while keeping full control over your code.

3. Get Rid of Unnecessary Comments

Writing good code comments can help others understand why your code is doing what it’s doing.

But I see developers writing too many comments, even where there is no need.

I believe that, whenever possible, good code should document itself.

Here’s an example of a not so helpful comment:

// Adding 10 to the result 
total = total + 10;

You see, here the comment doesn’t make sense, and it doesn’t really add anything to the code (or our understanding of it).

It’s a better practice to write comments only if they’re important in helping a reviewer understand why you did something in particular or if there’s some ambiguity that needs explaining.

Here’s an example:

// Adding 10 because the client requires a 10% buffer for calculations 
total = total + 10;

Now you can see that here the comment gives a clear idea about why the programmer added 10 to the total.

4. Follow the DRY Principle

I’ve seen a lot of programmers repeating the same logic or adding the same functionality in different files.

Well, you don’t need to repeat the same code everywhere because it makes the process much more complex. Keep your code DRY (Don’t Repeat Yourself).

Instead, abstract that logic into a single reusable function.

For example, instead of writing the same logic in different files:

if (user.age > 18 && user.age < 65) { 
 // Do something 
}

if (user.age > 18 && user.age < 65) { 
 // Do something else 
}

You can create a reusable function so that you can use the logic everywhere, as shown below:

function isWorkingAge(age) { 
 return age > 18 && age < 65; 
}

if (isWorkingAge(user.age)) { 
 // Do something 
}

In short — write once, and use everywhere.

5. Fix Your Code Formatting & Follow a Consistent Style

This is another simple hack, but many devs don’t even think about it.

First of all, you need to format your code with proper indentation.

You can just install a VS Code extension/linters like Prettier, ESLint, or Flake8, depending on the programming language you use. Configure a few settings, and you’re good to go.

These linters can help you write better code by finding mistakes, helping you follow coding rules, and keeping your code consistent. They can also catch errors, make your code easier to read, and save time on fixing bugs and reviews.

But fixing your formatting doesn’t just mean it’s clean code – it’s way more than that.

Beyond formatting, you should stick to a consistent style guide for things like function names or variable names.

For example, here’s some code that has an inconsistent style:

let total_price;  
let UserData;  
function getuser() {}

But some of you may ask, why is the code inconsistent?

Well, it uses several different naming conventions – like total_price uses snake_case, UserData uses PascalCase, and getuser() is in lowercase instead of camelCase.

This makes your code harder to read and more confusing. Instead, you can follow a consistent style. Here’s how:

let userData; 
let totalPrice; 
function getUser() {}

And just to let you know, JavaScript typically follows camelCase for variables and functions, so names like getUser(), userData, and totalPrice would be more consistent.

No matter whether you’re working in a team or solo, sticking to one style is a good idea. It makes the code clean, and the reviewer can easily go through it.

6. Don’t Let Your Functions Do Too Much

As a programmer, I know that sometimes you need to write complex logic inside a function.

But most often, programmers include too much logic in a single function, causing it to do more than one thing at a time. These functions become too complex, making them hard to read or understand.

It’s better to create multiple smaller functions, with each function handling a single responsibility.

Here’s an example of a slightly too complex function:

function calculateCart(items) {
 let total = 0;
 for (let i = 0; i < items.length; i++) {
 total += items[i].price * items[i].quantity;
 }
 return total > 100 ? total * 0.9 : total;
}

You see, this single function does too much—it applies discounts if applicable, and calculates the total price based on quantity, making it hard to reuse for specific use cases.

A better way is to split it into three functions:

• One to apply the discount (if applicable).

• One to calculate the total price based on quantity.

• One to get the total and apply the discount if needed.

This makes the code cleaner and easier to manage. Here’s an improved version:

function calculateCart(items) {
 const total = getCartTotal(items);
 return applyDiscount(total);
}

function getCartTotal(items) {
 return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
}

function applyDiscount(total) {
 return total > 100 ? total * 0.9 : total;
}

You see, instead of writing everything in one long block, the logic is broken into smaller, clearer functions.

And that’s what makes it easier for you (and everyone else) to understand.

7. Organize Your Files and Folders Properly

Now comes the most important part.

When you’re working on a big project, it makes no sense to dump all your code into one single folder with a bunch of random files. It’s become a nightmare for anyone trying to review the code or find a specific file.

Think about it — going through 50 files just to fix a bug. Nobody wants that.

Instead, try organizing your project into multiple folders based on pages or features.

And don’t stop there — break large files into smaller, specific modules based on functionality. This way, everything is neat, easy to find, and makes sense at first glance.

Here’s a bad example of a project structure:

project-folder/  
│  
├── index.html  
├── app.js  
├── helpers.js  
├── data.js  
├── user.js  
├── product.js

It’s messy, right? Now, here’s how you can improve it:

project-folder/  
│  
├── pages/  
│   ├── home/  
│   │   ├── HomePage.js  
│   │   ├── HomePage.css  
│   │   └── HomePage.test.js  
│   ├── user/  
│   │   ├── UserPage.js  
│   │   ├── UserPage.css  
│   │   └── UserPage.test.js  
│   └── product/  
│       ├── ProductPage.js  
│       ├── ProductPage.css  
│       └── ProductPage.test.js  
├── components/  
│   ├── Header.js  
│   ├── Footer.js  
│   └── Button.js  
├── utils/  
│   └── api.js  
└── index.js

See how simple this is?

You have separate folders for pages, components, and utilities. Inside each folder, files are organized by purpose and given clear names.

For example, if you need something for the product page, you’ll know exactly where to find it.

Wrapping Up

In this article, you learned the basics you need to get started writing clean, efficient, and maintainable code.

We discussed how to write clean code, use AI tools, apply proper code formatting techniques, structure functions effectively, and follow other best practices.

If you apply these tips consistently, you’ll significantly improve your coding skills and write cleaner code.

I hope you liked it.

You can connect with me on Substack, and Twitter.

Also, if you're interested in learning more about AI, you can subscribe to my newsletter, AI Made Simple, where I dive deeper into practical AI strategies for everyday people.

In this article, I’ll explain and demonstrate what clean code is. Then I’ll share my favorite clean code patterns for building modern Agile applications.

I won’t use complex jargon. I’ll hit you with simple, clear JavaScript examples that focus on the core concepts. Straight to the point, no nonsense – that’s how I roll.

Let’s get started.

Table of Contents

1. The Cost of Bad Code

2. Clean Coder vs. Messy Coder

3. AI Can’t Save You If Your Code is a Mess 🗑️

4. 12 Clean Code Design Patterns for Building Agile Applications ⚖️

   • 🌿 Use Names That Mean Something

   • 🔨 Keep Functions Laser-Focused (SRP)

   • 🚪 Use Comments Thoughtfully

   • ⚡ Best Practices for Writing Good Comments

   • 🧩 Make Your Code Readable

   • 🏌️ Test Everything You Write

   • 💉 Use Dependency Injection

   • 📂 Clean Project Structures

   • 🤹‍♂️ Be Consistent with Formatting

   • ✋ Stop Hardcoding Values

   • 🤏 Keep Functions Short

   • ⛺ Follow the Boy Scout Rule

   • 🏟️ Follow the Open/Closed Principle

5. Modern Best Practices to Help You Write Clean Code: A Summary 🥷

6. Automated Tools for Maintaining Clean Code ⚓

   • 1️⃣ Static Analysis

   • 2️⃣ Automated Code Formatting

   • 3️⃣ Continuous Integration (CI) Testing

   • 4️⃣ CI/CD pipelines

7. The Role of Documentation in Agile Software Development 🚣

8. Conclusion 🏁

9. Frequently Asked Questions About Clean Code 🧯

In Agile, where change is the only constant, clean code is your armor. It makes you adaptable, swift, and, most importantly, in control.

Here’s the truth: writing clean code is not optional if you want to survive in the software development industry. Fortunately, we human beings are able to master clean code with some effort and practice.

The Cost of Bad Code

To explain this stack bar graph, in the initial development phase, bad code is slightly more costly to change than clean code.

But as we move into the maintenance and refactoring phases, the gap widens significantly, with bad code costing nearly twice as much as clean code.

By the legacy phase, bad code reaches 100% cost – now it’s extremely expensive to update, while clean code remains more manageable at 45%.

As of now, the most recent analysis on the cost of poor software quality in the U.S. is the 2022 report by the Consortium for Information and Software Quality (cisq.org). This report estimates that poor software quality cost the U.S. economy at least $2.41 trillion in 2022, with technical debt accounting for about $1.52 trillion of this amount.

You can read more about that here.

Recent discussions continue to highlight the significant impact of technical debt on software quality and business performance.

For instance, a 2024 survey indicated that for more than 50% of companies, technical debt accounts for greater than a quarter of their total IT budget. And this can really hinder innovation if it’s not addressed.

As you can see, there’s no doubt that bad code is a costly problem in software development.

Clean Coder vs. Messy Coder

Here’s a graph that shows the journey of two types of coders:

• ⚠️ The Messy Coder (Red line): Starts fast but crashes hard. The more lines they write, the more trouble they make.

• ⚡ The Clean Coder (Blue line): Starts slow but stays consistent. Growth doesn’t stop — it accelerates.

🫵 Now, you decide which line you want to follow.

AI Can’t Save You If Your Code is a Mess 🗑️

When you get stuck writing code, you might turn to AI. But let me tell you something: AI can’t save you if your code is a mess.

It’s like building a house on sand. Sure, it stands for a while, but one strong gust of wind or big wave, and it collapses.

Remember: AI is just a tool. If you don’t know how to write clean, scalable applications, you're setting yourself up for failure.

If you can’t maintain the code you write, you’re in trouble.

I’ve seen it over and over again: developers who know five programming languages. They can build apps, websites, software. They know algorithms and data structures like the back of their hand.

But when faced with a large project or someone else’s messy code, they crumble.

They’re like an aerospace engineer who designs and builds their own planes but doesn’t know how to fly them. They crash into their own code.

This was me...once upon a time. I’d write thousands of lines of code, only to realize I couldn’t even understand what I wrote last week. It was chaos for me.

But then it hit me — every developer struggles with this. It wasn't about how much I knew. It was about how I organized and structured what I knew. In other words, it was about knowing the art of programming itself.

I decided to escape this trap. After five months of intense work — four to five hours a day writing, designing, and researching — I created something I wish I had when I started programming. A book that’s a complete beginner’s guide: Clean Code Zero to One.

If you want to learn more about the book, I give you all the details at the end of this tutorial. So read on to learn more about writing clean code.

12 Clean Code Design Patterns for Building Agile Applications ⚖️

If your code doesn’t follow these modern clean code design patterns, you could be creating a ticking time bomb. These patterns are your tools. Master them and enjoy the success of your projects. Let me show you one by one.

🌿 Use Names That Mean Something

Naming your variables or functions b or x is not helpful. Call them what they are so they’re easier to understand. Here’s an example of both a bad and good variable name:

// Weak and vague
let b = 5;

// Strong and clear
let numberOfUsers = 5;

People who write unclear names don’t want to own their mistakes. Don’t be that person.

🔨 Keep Functions Laser-Focused (SRP)

A function should do one thing—and do it perfectly. This is called the Single Responsibility Principle (SRP).

Good code is like a hammer. It hits one nail, not ten. For example, if you are hiring someone to do everything in your company — finance, sales, marketing, janitorial work, and so on — they’ll likely fail miserably because they can’t focus one one thing. The same goes for your classes in code.

🚧 When a class or function does more than one thing, it becomes a tangled mess. Debugging it feels like solving a puzzle upside down. If your class handles both user input and database operations, for example, it’s not multitasking — it’s madness. Break it up. One method, one job.

🔥 My Rule: Your code works for you. Keep it sharp, focused, and controllable, or it’s going to control you. Here is how to make that happen:

// Clean: One job, one focus
function calculateTotal(a, b) {
    return a + b;
}

function logTotal(user, total) {
    console.log(`User: ${user}, Total: ${total}`);
}

// Messy: Trying to do EVERYTHING
function calculateAndLogTotal(a, b, user) {
    let total = a + b;
    console.log(`User: ${user}, Total: ${total}`);
}

🪧 When you mix tasks, you mix in confusion. As simple as that.

🚪 Use Comments Thoughtfully

There is a great saying among professional developers:

“ Code speaks for itself. ”

You don’t explain what a door does every time someone walks into a room, do you? Your code should work the same way.

Comments aren’t bad, but if your code can’t stand on its own, then you may have a problem.

🪧 A good comment should tell “why” not “how or what”. If a developer doesn’t understand “how” something works, then they likely aren’t going to understand “why” either.

Here are some short examples of good comments vs bad comments. I’ll also show you a real-world project for writing clean comments.

Example 1: Bad Comment 👎

// Multiply the price by the quantity to calculate the total
const total = price * quantity;

This is a bad comment because it simply repeats what the code already says. The code price * quantity is self-explanatory, so the comment doesn’t add anything useful.

Good Comment: 👍

If the code is clear and simple, you don’t need a comment.

const total = price * quantity;

Example 2: Bad Comment 👎

// Check if the user logged in
function isUserLoggedIn(session) {
    return !!session.user;
}

This comment is bad because it doesn’t explain why the isUserLoggin() exists. It just explains what happens. But we already know that this is an auth function. This comment is a waste of time.

Good Example 👍

// The user is authenticated before accessing protected resources
function isUserLoggedIn(session) {
    return !!session.user;
}

This is a good comment because it explains why the code exists. It tells us that the function checks if the user is authenticated before allowing access to sensitive parts of the app. It focuses on the bigger picture.

⚡ Best Practices for Writing Good Comments

1. Explain the “Why,” not the “What”:
   Write comments to explain the purpose or context of the code, not what the code is doing.

2. Avoid obvious comments:
   Don’t write comments for things the code already makes clear.

3. Keep them short and precise:
   Write concise comments that are easy to read and directly explain the purpose.

4. Update comments regularly:
   Outdated comments can mislead developers, so always update them when the code changes.

Real-World Example (with Good Comments) 🛒

Let’s implement these practices into a real-world project: a large e-commerce application. One function calculates shipping costs based on the order details. Here's the full code, I will explain each comment below:

// Shipping rules:
// - Free shipping for orders over $100
// - Standard shipping ($10) for orders below $100
// - Additional $5 for international orders

function calculateShipping(order) {
    let shippingCost = 0;

    // Check if the order qualifies for free shipping
    if (order.total >= 100) {
        shippingCost = 0; // Free shipping
    } else {
        shippingCost = 10; // Standard shipping cost
    }

    // Add additional cost for international orders
    if (order.isInternational) {
        shippingCost += 5;
    }

    return shippingCost;
}

// Example usage
const order1 = { total: 120, isInternational: false };
const order2 = { total: 80, isInternational: true };

console.log(calculateShipping(order1)); // Output: 0
console.log(calculateShipping(order2)); // Output: 15

At the start of the function, we include a comment explaining the rules for shipping costs. This gives the reader an overview of the logic without needing to read the full code.

// Shipping rules:
// - Free shipping for orders over $100
// - Standard shipping ($10) for orders below $100
// - Additional $5 for international orders

Then, the first condition checks if the order total is greater than or equal to $100. A comment here clarifies why free shipping is applied.

// Check if the order qualifies for free shipping
if (order.total >= 100) {
    shippingCost = 0; // Free shipping
}

The second condition applies an additional charge for international shipping. The comment explains why the extra cost is added.

// Add additional cost for international orders
if (order.isInternational) {
    shippingCost += 5;
}

Why are these comments good?

Imagine you’re working in a team of 20 developers. Someone reads the calculateShipping function six months later. Without these comments, they might waste time guessing why international orders have an extra fee. Good comments clarify the why and save hours of frustration.

🧩 Make Your Code Readable

If someone reading your code feels like they’re solving a riddle, you’ve already become a troublemaker. Here is the proof:

// Clean: Reads like a story
if (isLoggedIn) {
    console.log("Welcome!");
} else {
    console.log("Please log in.");
}

// Messy: Feels like chaos
if(isLoggedIn){console.log("Welcome!");}else{console.log("Please log in.");}

If your code is messy and hard to read, it will confuse others—and even yourself later! Imagine coming back to your own code after six months and feeling like you’re reading a foreign language. Readable code saves time, reduces bugs, and makes everyone’s life easier.

🍵 Why is Readability Important?

1. For yourself: When you revisit your code after weeks or months, clean code helps you pick up where you left off without wasting time figuring out what you did.

2. For your team: If someone else reads your code, they shouldn’t have to solve a puzzle. Clean code makes teamwork smoother and prevents miscommunication.

3. Fewer bugs: Clear code is easier to debug because you can quickly spot mistakes.

🧙‍♂️ How to Write Readable Code

Let’s build a simple program to manage books in a library. We’ll make it clean and readable and then I will break down this code below:

// A class to represent a book
class Book {
    constructor(title, author, isAvailable) {
        this.title = title;
        this.author = author;
        this.isAvailable = isAvailable;
    }

    borrow() {
        if (this.isAvailable) {
            this.isAvailable = false;
            console.log(`You borrowed "${this.title}".`);
        } else {
            console.log(`Sorry, "${this.title}" is not available.`);
        }
    }

    returnBook() {
        this.isAvailable = true;
        console.log(`You returned "${this.title}".`);
    }
}

// A function to display available books
function displayAvailableBooks(books) {
    console.log("Available books:");
    books.forEach((book) => {
        if (book.isAvailable) {
            console.log(`- ${book.title} by ${book.author}`);
        }
    });
}

// Example usage
const book1 = new Book("The Clean Coder", "Robert Martin", true);
const book2 = new Book("You Don’t Know JS", "Kyle Simpson", false);
const book3 = new Book("Eloquent JavaScript", "Marijn Haverbeke", true);

const library = [book1, book2, book3];

displayAvailableBooks(library); // Show available books
book1.borrow(); // Borrow a book
displayAvailableBooks(library); // Show available books again
book1.returnBook(); // Return the book
displayAvailableBooks(library); // Final list

We created a Book class to represent each book. It has properties like title, author, and isAvailable to track its status.

• The borrow method checks if the book is available. If yes, it marks it as unavailable and prints a message.

• The returnBook method makes the book available again.

• The displayAvailableBooks function loops through the library and prints only the books that are available.

• We create three books (book1, book2, book3) and store them in a library array.

• We borrow and return books, showing how the list of available books changes.

As you can see, readable code is not just about style. It saves time, prevents bugs, and preserves your code as useful for years to come.

🏌️ Test Everything You Write

If you don’t take the time to write tests, you shouldn’t be surprised if your code breaks. If you do want to write tests, follow this unit testing strategy to catch problems ahead.

What Is Unit Testing?

Concretely, unit testing checks individual parts of your code (like functions or classes) to ensure they work correctly. Just like checking each brick of your house for soundness before building the walls.

Let me give you an example of how unit testing works:

class Calculator {
    add(a, b) { return a + b; }
    subtract(a, b) { return a - b; }
}

// Test it (Unit Test)
const calculator = new Calculator();
console.assert(calculator.add(2, 3) === 5, "Addition failed");
console.assert(calculator.subtract(5, 3) === 2, "Subtraction failed");

Here’s what’s going on in this code:

First, we create the calculator class:

class Calculator {
    add(a, b) { return a + b; }
    subtract(a, b) { return a - b; }
}

The Calculator class has two methods: add and subtract.

• add(a, b) takes two numbers and returns their sum.

• subtract(a, b) takes two numbers and returns their difference.

Next, we set up the tests:

const calculator = new Calculator();

Here, we’re creating an instance of the Calculator class to test its methods.

Then we write test cases:

console.assert(calculator.add(2, 3) === 5, "Addition failed");
console.assert(calculator.subtract(5, 3) === 2, "Subtraction failed");

console.assert(condition, message) checks if the condition is true. If it’s false, the message ("Addition failed" or "Subtraction failed") is displayed in the console.

• First test: calculator.add(2, 3) === 5

  • Calls the add method with 2 and 3.

  • Checks if the result is 5.

• Second test: calculator.subtract(5, 3) === 2

  • Calls the subtract method with 5 and 3.

  • Checks if the result is 2.

So what happens if something breaks? It’s pretty simple to solve any issues that arise here. In this case, if the add or subtract method doesn’t work correctly, the test will fail. For example:

console.assert(calculator.add(2, 3) === 6, "Addition failed");

• The condition calculator.add(2, 3) === 6 is false.

• The console will display: "Addition failed".

Real-World Example: Testing a Login System 👥

Let’s test a simple login system to see how unit testing works in a real-world scenario.

class Auth {
    login(username, password) {
        return username === "admin" && password === "1234";
    }
}

// Test the Auth class
const auth = new Auth();
console.assert(auth.login("admin", "et5t45#@") === true, "Login failed for valid credentials");
console.assert(auth.login("user", "wrongpassword") === false, "Login succeeded for invalid credentials");

First, create the Auth class:

class Auth {
    login(username, password) {
        return username === "admin" && password === "1234";
    }
}

The login method checks if the username is "admin" and the password is "1234". If both match, it returns true – otherwise, false.

Next, set up the tests:

const auth = new Auth();

Create an instance of the Auth class. Then write the test cases:

console.assert(auth.login("admin", "1234") === true, "Login failed for valid credentials");
console.assert(auth.login("user", "wrongpassword") === false, "Login succeeded for invalid credentials");

• First test: Checks if valid credentials ("admin", "1234") succeed. If not, "Login failed for valid credentials" is displayed.

• Second test: Checks if invalid credentials ("user", "wrongpassword") fail. If not, "Login succeeded for invalid credentials" is displayed.

🌱 Why testing results in clean code:

1. You naturally write smaller, more focused functions to make your code testable

2. Tests verify that your code behaves as expected under different conditions.

3. With tests in place, you can confidently update your code, knowing the tests will catch any mistakes.

💉 Use Dependency Injection

Hardcoding dependencies is like tattooing someone’s name on your forehead — it’s permanent, can be abrasive, and locks you in.

So, what does Dependency Injection do? It lets you manage your code's relationships by passing dependencies as arguments. It’s flexible, adaptable, and maintainable.

To demonstrate how it works, here I’m using the Nodemailer dependency for sending emails to users:

// Dependency: Sending emails with Nodemailer
const nodemailer = require('nodemailer');
function sendEmail(to, subject, message) {
    const transporter = nodemailer.createTransport({ /* config */ });
    return transporter.sendMail({ from: "programmingwithshahan@gmail.com", to, subject, text: message });
}

⚠️ To save yourself from risk, make sure to avoid hardcoding dependencies. Use abstraction or configuration files for secure maintenance.

This is just one example. As a developer, you may use hundreds of libraries or dependencies.

I’m not saying you shouldn’t rely on dependencies/libraries at all, as nowadays it is hard to avoid them. But you should be very careful before installing them in your coding projects.

You should check the security, performance, quality, or functionality of an organization's software systems. Because they sometimes contain risks that can ruin your entire project.

🚧 Always control your tools, don't let them control you.

📂 Clean Project Structures

A well-organized project is the difference between a trash heap and a high-end boutique.

Here is how each folder should be organized:

If your codebase looks like a junk drawer, you’ve already caused trouble for your future self.

Let’s go through the clean project structure you can see above to better understand it:

1. myProjet/src

This is the main container for your entire application. Everything your app needs is stored inside this folder. It has subfolders to keep things tidy and managed in one place.

2. components

This is where you keep all the reusable pieces of your app. You can use these components in multiple places without building them again.

3. services

This is the "brain" of your app. It handles all the work behind the scenes for both the frontend and backend. emailService.js, userService.js and productService.js are some of the example files for your services folder.

4. utils

This contains all the small, handy tools you need to make your application run smoothly and make your life easier. For example, formatedate.js, validateEmail.js and generateId.js are some of the common utils files to make reusable pieces of components for your entire project.

5. tests

Conventionally, test files are typically located outside the src folder, at the project root level. This keeps your production code (src) separate from your test code (tests), making it cleaner and easier to manage. Have a look:

myProject/
├── src/              # Production code
│   ├── components/
│   ├── services/
│   └── utils/
├── tests/            # Test files
│   ├── components/
│   ├── services/
│   └── utils/
├── package.json      # Project configuration
└── README.md         # Documentation

Some developers may prefer creating one testing file inside the test folder to test everything in one place. Unfortunately, it may feel clean at first, but as your project grows, you’ll have to find and search for specific code blocks. It’s ugly and can produce unexpected testing results. So breaking them into multiple testing files inside the tests folder is highly recommended.

Real-world example 📧

So let me create a clean, durable project structure for you to apply in any future projects you might work on. Needless to say, clean project structure is the foundation of building a maintainable project.

From our previous email sending application example, we will write a clean project structure for this app. We want to build an application that sends emails to users. Your clean project structure for this app should look like this:

As you can see, I packed every subfolder and file inside the src folder which is the main container of our application. Inside the src folder, we created components, services, utiles. Finally, we have a manageable test folder outside the src folder to test each component independently. This test folder has nothing to do with our production code that is located inside the src folder.

🤹‍♂️ Be Consistent with Formatting

Don’t write code like you’re 10 different people. Be consistent with your formatting.

Use tools like Prettier or ESLint to enforce a consistent style. If every file looks different, you’re creating chaos that no one wants to fix.

I would say that consistency in formatting is one of the most important aspects of writing clean code.

Have a look...

// Always use 2 spaces for indentation
function calculateArea(width, height) {
  if (width <= 0 || height <= 0) {
    throw new Error("Dimensions must be positive numbers.");
  }
  return width * height;
}

// Add meaningful whitespace for readability
const rectangle = {
  width: 10,
  height: 20,
};

// Clear separation of logic
try {
  const area = calculateArea(rectangle.width, rectangle.height);
  console.log(`Area: ${area}`);
} catch (error) {
  console.error(error.message);
}

Let’s examine some of the aspects of this code that make it clean:

1️⃣ Consistent Indentation

Why 2 or 4 spaces? It’s clean, minimal, and universally accepted in many JavaScript style guides. It doesn’t overwhelm the eyes, and the code structure stands out clearly. When you mix inconsistent indentation (2 spaces here, 4 spaces there), you confuse people—and confused people make mistakes.

2️⃣ Meaningful Whitespace: Giving Code Room to Breathe

That extra line break between the rectangle definition and the try block is like a pause in a sentence — it gives the reader time to process.

3️⃣ Clear Separation of Logic: Modular Thinking

try {
  const area = calculateArea(rectangle.width, rectangle.height);
  console.log(`Area: ${area}`);
} catch (error) {
  console.error(error.message);
}

Look at how the logic is divided into clear sections:

• First, the calculation (calculateArea function).

• Then, the output (console.log).

• Finally, error handling (catch block).

Each task has its own space and purpose.

4️⃣ Readable Error Handling

When you throw errors or log messages, you format them cleanly. No vague or cryptic messages here. A developer seeing this will immediately know the problem.

throw new Error("Dimensions must be positive numbers.");

🐦‍⬛ General tips for consistent formatting:

• Use 2 or 4 spaces for indentation consistently throughout your codebase. Avoid tabs to maintain uniformity across different editors.

• Keep lines to a maximum of 100-120 characters to prevent horizontal scrolling and improve readability.

• Group related logic together and separate blocks of code with blank lines to highlight their purpose.

• Finally, avoid over-aligning code. Instead, let indentation naturally guide the flow of logic.

✋ Stop Hardcoding Values

Hardcoding values is a lazy way to code. Here is the proof:

// Bad: Hardcoded and rigid
function createUser() {
    const maxUsers = 100;
    if (currentUsers >= maxUsers) throw "Too many users!";
}

// Clean: Dynamic and flexible
const MAX_USERS = 100;
function createUser() {
    if (currentUsers >= MAX_USERS) throw "Too many users!";
}

You see, changing this variable won’t surprise you in the future. You know exactly where to find it to change uncertain values.

Its best to store your fixed values in the global configuration (config) file.

🪧 So, avoid hardcoding values at all costs. Hardcoding is the shortcut that may drive your future self (or others) crazy.

🤏 Keep Functions Short

If your function is longer than 20 lines, it’s probably trying to do too much.

Short functions are sharp functions. They hit their mark every time.

Long, bloated functions are messy and hard to read, but short functions are clear and focused. Here is how your large functions should break down:

function updateCart(cart, item) {
    addItemToCart(cart, item);
    let total = calculateTotal(cart);
    logTransaction(item, total);
    return total;
}

function addItemToCart(cart, item) {
    cart.items.push(item);
}

Let me explain this code so you understand why breaking down large functions is a winning strategy.

1. The Main Function: updateCart() calls smaller helper functions to handle specific tasks like:

   • Adds the item to the cart.

   • Calculates the total price.

   • Logs the details of the transaction.

   • Finally, it returns the total price.

Instead of one long block of code that tries to do everything, it delegates tasks to helper functions.

2. Helper Function: addItemToCart() This function only handles adding the item to the cart. if you need to change how items are added (for example, checking for duplicates). You could just edit this small function instead of digging through a giant block of code in updateCart. That’s how you write clean code functions that’s a joy to read and easy to maintain.

What Happens If Functions Are Too Long? 💤

Let’s say you didn’t break down the updateCart function. Here’s what it might look like:

function updateCart(cart, item) {
    cart.items.push(item);
    let total = 0;
    for (let i = 0; i < cart.items.length; i++) {
        total += cart.items[i].price;
    }
    console.log(`Added ${item.name}. Total is now $${total}.`);
    return total;
}

What are the problems here?

• It’s trying to do everything.

• It’s hard to read, especially if it grows bigger.

• If something breaks, you’ll waste time figuring out which part is the problem.

Now the choice is yours: stick with the messy all-in-one approach or practice the clean one function one job mindset.

⛺ Follow the Boy Scout Rule

Always leave your campsite cleaner than you found it.

Let me break it down for you. You don’t just use something and leave it worse than before. That’s inconsiderate behavior. Real professionals leave things better than they found them.

In coding terms, every time you touch the codebase, make it better. Clean it up, refactor messy parts, and improve readability. If you don’t, you’re just piling on garbage that will eventually collapse on your head.

Here is an example. Instead of improving it, we’re just adding more layers of complexity:

// Original code: Hard to read, poorly named variables
function calc(a, b) {
  let x = a + b;
  let y = x * 0.2;
  return y;
}

// We're adding to it but not cleaning it up
function calcDiscount(a, b, discountRate) {
  let total = calc(a, b);
  let final = total - discountRate;
  return final;
}

After: it gets better every time. Here’s how a disciplined coder works — they improve as they go:

// Improved code: Clear names, refactored for clarity
function calculateSubtotal(price, quantity) {
  return price * quantity;
}

function calculateDiscountedTotal(price, quantity, discountRate) {
  const subtotal = calculateSubtotal(price, quantity);
  const discount = subtotal * discountRate;
  return subtotal - discount;
}

Now, anyone can tell what’s happening at a glance. Because we’ve broken down the code into smaller, more focused functions. Thus, adding new features won’t break existing functionality. 🏕️

🏟️ Follow the Open/Closed Principle

This design principle suggests your code should be designed to allow extensions without changing the existing foundation.

You want to add features — not rip it apart every time you upgrade. Modifying old code to fit new requirements is exactly like trying to rebuild your house every time you buy new furniture. It’s not sustainable.

Let’s see how you can build smarter, scalable code that lets you add features without breaking everything else.

Before: Violating the principle

You’ve got a class to handle payments — simple enough. At first, it just handles credit cards.

But then your boss shows up and says, “Hey, now we need PayPal support.”

And because you didn’t bother learning clean code, your code looks like a spaghetti monster straight out of a legacy enterprise system from 1995. Here’s the masterpiece you’ve crafted:

class PaymentProcessor {
  processPayment(paymentType, amount) {
    if (paymentType === "creditCard") {
      console.log(`Processing credit card payment of $${amount}`);
    } else if (paymentType === "paypal") {
      console.log(`Processing PayPal payment of $${amount}`);
    } else {
      throw new Error("Unsupported payment type");
    }
  }
}

const paymentProcessor = new PaymentProcessor();
paymentProcessor.processPayment("creditCard", 100);
paymentProcessor.processPayment("paypal", 200);

Alas! Every new payment type (like Apple Pay, Google Pay, and so on) requires modifying the processPayment method. Needless to say, you risk breaking existing functionality while adding new features. If you had learned this principle, you might not be in this mess.

Don’t worry: I’ll help you to fix this. First, we need to refactor the code. Instead of modifying the existing class, we’ll extend its functionality using polymorphism:

javascriptCopy code// Base class
class PaymentProcessor {
  processPayment(amount) {
    throw new Error("processPayment() must be implemented");
  }
}

// Credit card payment
class CreditCardPayment extends PaymentProcessor {
  processPayment(amount) {
    console.log(`Processing credit card payment of $${amount}`);
  }
}

// PayPal payment
class PayPalPayment extends PaymentProcessor {
  processPayment(amount) {
    console.log(`Processing PayPal payment of $${amount}`);
  }
}

// Adding a new payment type? Just extend the class!
class ApplePayPayment extends PaymentProcessor {
  processPayment(amount) {
    console.log(`Processing Apple Pay payment of $${amount}`);
  }
}

// Usage
const payments = [
  new CreditCardPayment(),
  new PayPalPayment(),
  new ApplePayPayment(),
];

payments.forEach((payment) => payment.processPayment(100));

Now, adding new payment methods doesn’t require changing the existing PaymentProcessor class. You just created a new subclass. So the original code remains untouched, meaning there’s no risk of breaking existing features.

Each payment type has its own class, and adding PayPal payment support, for example, doesn’t break the code. Now you can reply to your boss: “Of course, I will add this feature in 5 minutes.” Your promotion is waiting for you to accept it.

I share even more tips in my book Clean Code Zero to One.

Modern Best Practices to Help You Write Clean Code: A Summary 🥷

Now let me show you the best practices and summarise our 12 Clean Code design principles to help you write clean code for agile application development.

🔎 Common Code Smells and How to Fix Them

• 💊 Duplication: If you're copying code, you’re creating more work for yourself. Extract it into a function, and do it right.

• 🛤️ Long methods: If your method needs a scroll bar, it's doing too much. Break it down, keep it focused.

• 👑 King objects: No class should be doing everything. Simplify responsibilities, or your codebase will become messy.

💬 Effective Commenting Practices

• 💭 When to comment: Only comment if the code isn't clear. If it is, comments are just clutter.

• 🫗 Clarity: Comments should tell why, not what. If your code needs explaining, it might be too complex.

• 🌴 Avoid redundancy: Don't comment what's obvious. If your function is addNumbers, don't comment it does that.

🧼 Refactoring Techniques for Clean Code

• 🏭 Extract methods: Big methods? Break them down. It's not just about cleanliness –– it's about control.

• 🫕Rename variables: If your variable names don’t shout their purpose, change and improve them. Precision in naming is precision in thought.

• 🍃 Simplify conditionals: If your conditionals look like algebra, simplify them. If a == true, just write if(a).

🧪 Testing and Clean Code

• 🧙 Unit tests: Test every piece of code like you're interrogating a suspect. No stone unturned.

• 🏇TDD (Test Driven Development): Write tests first. It's not just about catching bugs, it's about knowing exactly what your code should do before you write it.

• 🧽 Clean tests: Your tests should be as clean as your code. If they're messy, they’re not going to be helpful.

🐛 Error Handling and Clean Code

• ⁉️ Exceptions: Use them. They're not just for errors, they're also for keeping your code clean from error clutter.

• 🖍️ Fail fast: If something's wrong, stop right there. Don't let errors add up. Deal with them immediately.

• 🚨 Logging: Log like you're documenting a crime scene. Clear, precise, and only what's necessary.

🌱 Code Reviews and Clean Code

• 🚢 Process: Have a system. No cowboy coding. Review, critique, improve.

• 🔪 Tools: Use tools that make reviews easy. They're not just for catching mistakes, they're also for teaching discipline.

• 🧦 Culture: Cultivate a culture where feedback is gold. Help your team learn how to handle and receive critiques.

Automated Tools for Maintaining Clean Code ⚓

Tools and automation techniques can be really helpful in writing clean code. If you’re not using the right tools and automating things to save yourself time, you’re missing out.

You think you can "eyeball" your way through code quality? Guess again. Without automation, this is what happens:

1. 👎 You miss obvious mistakes because you're "too busy."

2. 🤕 Your code looks different in every file, making collaboration a headache.

3. 🪦 Deployment breaks because you skipped a critical test.

Successful developers use the right tools to automate code and get things done. Here are four strategies for maintaining clean code using modern tools.

1️⃣ Static Analysis

Static analysis is actually a code inspector that reads through your code and points out potential issues early on. The best part? It works before runtime, catching errors that could otherwise lead to crashes, downtime, or embarrassing bugs.

How does it work?

1. Syntax checking: It looks at your code to analyze everything written in the correct syntax. If you misspell a variable or forget a closing bracket, it’ll call you out instantly.

2. Code quality rules: Tools like ESLint enforce rules like consistent indentation, avoiding unused variables, and sticking to best practices.

3. Error prevention: It identifies logic errors, such as using variables that haven’t been defined, or making comparisons that don’t make sense.

Here’s how static analysis works in action:

🚨 Before static analysis:

let sum = (a, b) => { return a + b; }
console.log(sume(2, 3)); // Typo, unnoticed until runtime

• Problem: The typo in sume will only cause an error when the code runs, and that could lead to frustrating debugging sessions or worse — breaking the app in production.

🚑 After static analysis (using ESLint):

codeError: 'sume' is not defined.

• Solution: ESLint immediately flags the typo before you even run the code. The error is caught early, saving you time and headaches.

2️⃣ Automated Code Formatting

Before Formatting:

function calculate ( x , y ){ return x+ y;}
console.log( calculate (2,3 ) )

• Problem: Inconsistent spacing and formatting make the code harder to read.

After using Prettier:

function calculate(x, y) {
  return x + y;
}
console.log(calculate(2, 3));

• Solution: Clean, consistent, and professional formatting is applied automatically. No more nitpicking over spaces or alignment.

Pretty basic stuff though. I covered this in case you write code in notepad or something where IDE is not provided (for example, a job interview).

3️⃣ Continuous Integration (CI) Testing

CI testing make sure every new change to your code is verified automatically. It’s like a safety net that catches bugs introduced during development. CI tools run your tests every time you push code, so nothing breaks after deployment.

How Does CI Testing Work?

1. Triggers on change: Each time code is committed, the CI tool (like GitHub Actions, Jenkins) runs automated tests.

2. Feedback: It gives you instant feedback if something fails.

3. Prevents broken code: Commits only clean, and the working code gets merged into the main branch.

4️⃣ CI/CD pipelines

We also use CI/CD pipelines as a continuous process that includes code building, testing, and deployment, while CI testing is a part of that process that focuses on automating the testing of code changes.

Differece between CI/CD pipelines vs CI testing:

• CI/CD pipelines: A CI/CD pipeline combines code building, testing, and deployment into a single process. This process make sure that all changes to the main branch code are releasable to production. CI/CD pipelines can reduce deployment time, decrease costs, and improve team collaboration.

• CI testing: CI testing is the process of automatically testing code changes that are integrated into a central repository. CI testing focuses on making sure the codebase is stable and that integration issues are resolved. CI testing help developer build software that is stable, bug-free, and meets functional requirements

🚧 This is what CI testing CI/CD pipelines concepts are really about. Not as complex as it seems. So let me elaborate more on CI testing with GitHub Actions, as we usually run tests through automated tools nowadays.

⚡ Continuous Integration (CI) Testing with GitHub Actions

As I said earlier, CI tools run automated tests every time you push code or open a pull request. This guarantees that only working, bug-free code gets merged into the main branch.

How to Set Up CI Testing with GitHub Actions

Step 1: Create Your Repository

Set up a GitHub repository for your project. Then, push your code to GitHub using the following commands:

git init
git add .
git commit -m "Initial commit for CI Testing"
git branch -M main
git remote add origin https://github.com/codewithshahan/codewithshahan.git
git push -u origin main

Or you can create a new repo from your GitHub account without using the command. Just login to your GItHub account and visit dashboard. Here you will find a “New” button to create a brand new repo:

Step 2: Add a GitHub Actions Workflow

Navigate to your repository’s Actions tab. To do this, first, you have to visit your repo on Github (you will find the link after creating your repo). In this case, I created a new repo called “codewithshahan”. Here, look for the Actions tab on the right side of the navigation bar.

After navigating the Actions tab, scroll down a little and you will find the continuous integration section:

Choose a setup workflow yourself. I will use Node.js for this project.

After clicking the configure button, a node.js.yml file will be created automatically, and you can adjust the code depending on your goals.

I won’t go into detail about how should modify your .yml file. It depends on your project goals and personal preference. Also, it is a whole different broader topic and as this article has already become quite long, so I’ll explain it in a future article. For now, just stick with this foundational knowledge.

This CI Testing workflow is best for modern application development. Your app remains stable while incorporating key features including testing (e,g. Dark Mode), Building and deploying applications directly within your GitHub repository. This way, you can push your code confidently, knowing your code is always clean and ready for production.

The Role of Documentation in Agile Software Development 🚣

If you want your code to be top-notch, you need to understand how to write good documentation. If you think documentation is just about scribbling down how the code works, you’re wrong. It's about explaining why it works, not just how it works. That’s where most people miss the mark.

1. 🚡 Create Useful Docs (Explain Why, Not Just How)

When you write documentation, you're not just throwing down some instructions for how to use the code. You're telling the next person (or even yourself in the future) why this piece of code exists in the first place. That’s the difference between good and bad documentation.

Bad docs leave people scratching their heads. They’re too vague, too simple, and they don’t answer the big questions. If your documentation is unclear, that likely means your thinking is unclear. You’re basically saying, "I don’t care if you understand this, it works, just use it." That’s not helpful.

Great documentation answers the tough questions:

• ✅ Why did you choose this approach over another?

• ✅ Why does this function exist? What problem does it solve?

• ✅ Why did you write this code the way you did?

If your docs are just regurgitating how to use the code, you’re not being as helpful as you can be. Start thinking deeper and explaining the reasoning behind everything.

2. ⏳ Keep the Docs Updated (Outdated Docs Are Worse Than No Docs)

Outdated documentation is the worst. In fact, it can be worse than having no docs at all. When you leave documentation that’s out of sync with the code, you’re doing your future self — or whoever has to deal with it next — a huge disservice.

Every time your code changes, your documentation needs to change too. It has to reflect the current state of things. Don’t mislead future developers (or yourself) by leaving outdated info that will only confuse them and waste their time. If something is no longer relevant, delete it. Outdated documentation is the equivalent of a cluttered mind — it holds you back.

Make it a habit to check and update your documentation regularly. The minute a line of code changes, so should your documentation. Period.

3. 🚆 Integrate Comments (Good Comments in Code Are Part of Documentation)

Here’s the deal — comments in your code should integrate with your documentation. Good comments aren’t just a crutch for developers who can’t explain their code elsewhere. They should improve your docs, not replace them.

Comments are supplements to your documentation. You write clean, understandable code that needs minimal explanation, but when something isn’t crystal clear, throw in a comment. Remember the rule for comments in your code: explain the why, not the how. It’s the same here. Don’t repeat yourself. Let your code do the talking. Comments should complement the bigger picture of your documentation, not act as a band-aid for sloppy code.

🪧 Great code should be self-explanatory. Fix the code, then add comments for clarification if necessary. Keep comments clean, short, and to the point.

If you want to write clean, efficient, and maintainable code, documentation is key. Stop thinking of docs as an afterthought or something you do to fill space. It’s an extension of your code — your way of communicating clearly and effectively. It’s your roadmap for future developers, and it’s a reflection of your thought process.

Conclusion 🏁

Clean code isn't a nice-to-have –– it's a must-have for those who aim to lead. It's about control, efficiency, and improvement over time in the long run. And ultimately, it’ll help you succeed in the game of agile software development.

🪧 If you want to truly master your craftsmanship, write clean code, and let the efficiency speak for itself.

Frequently Asked Questions About Clean Code 🧯

1. What is clean code? It's code that doesn't make you want to throw your laptop out the window.

2. Why is clean code important in Agile? Because Agile is about speed and change, and you can't be quick with a mess.

3. What are code smells? Signs that you're about to lose control of your codebase.

4. How can I improve commenting? Only comment on what's necessary, and make sure each comment adds value, not noise.

Thank you for being with me. You can visit my Twitter account or my website to read more posts about clean code and Agile application development. Until next time… keep improving your codebase.

If you’re serious about mastering clean code and taking your programming career to the next level, then my book is for you: Clean Code Zero to One. This book is your full guide from zero to one in clean code, from messy code to masterpiece. I am offering a 50% discount using the code "earlybird" — only for the first 50 copies. Plus, there’s a 30-day money-back guarantee — no risk, all reward.

Programs are meant to be read by humans and only incidentally for computers to execute. - Donald Knuth

Have you ever heard that programmers spend more time reading code than writing it? Well, I’ve found that this is often true: as a developer, you’ll often spend more time reading and thinking about code than actually writing code.

This means that, however optimally you intend to make your code run, it’s also important that it’s delightful and easy to read.

In this article, we’ll look at an example function: createOrUpdateUserOnLogin. It lives in a JavaScript codebase far away and it’s begging to be made delightful to read. We will look at createOrUpdateUserOnLogin, highlight what makes it hard to read and why, and eventually refactor it to make it easier to read and understand.

The function is written in JavaScript and uses JSDoc to document its parameters. Knowledge of JavaScript is not necessarily important because the logic in the function will be explained in detail. JSDoc is only used to document what the function’s parameters represent.

The Problematic Function

This function is not made-up. It is a real function in the codebase of an application with more than a thousand users. Here it is:

/**
 * @param {Object} dto
 * @param {string} dto.email
 * @param {string} dto.firstName
 * @param {string} dto.lastName
 * @param {string} [dto.photoUrl]
 * @param {'apple' | 'google'} [dto.loginProvider]
 * @param {string} [dto.appleId]
 * @returns {string} token - access token
 */
async function createOrUpdateUserOnLogin(dto) {
  let user;

  if (dto.loginProvider == "apple") {
    user = await findOneByAppleId(dto.appleId);
    if (user?.isDisabled) {
      throw new Error("Unable to login");
    }

    if (user && !user.verified) {
      user = await setUserAsVerified(user.email);
    }

    if (!user) {
      user = await findOneByEmail(dto.email);

      if (user && dto.appleId) {
        user = await updateUserAppleId(user, dto.appleId);
      }

      if (user && !user.verified) {
        user = await setUserAsVerified(user.email);
      }
    }
  } else {
    user = await findOneByEmail(dto.email);
    if (user?.isDisabled) {
      throw new Error("Unable to login");
    }

    if (user && !user.photoUrl && dto.photoUrl) {
      user.photoUrl = dto.photoUrl;
      user = await updateUserDetails(user._id, user);
    }

    if (user && !user.verified) {
      user = await setUserAsVerified(user.email);
    }
  }

  if (!user) {
    user = await this.usersService.create(loginProviderDto);
  }

  return await this.createToken(user);
}

Perhaps you can tell by reading through and studying the code that it is quite hard to follow. If you leave your computer for a break right after reading this function, there is a good chance you won’t remember what exactly it does when you get back.

But this isn’t, and shouldn’t be, the case when you read a good story, regardless of its length. You can follow it easily and remember the basic details after hearing it.

The function is executed when a user attempts to sign in or sign up. Users can be authenticated using their Google account or their Apple account and the function has to return an access token on a successful attempt.

Some users have disabled their account. Those users are not allowed to authenticate successfully. The logic of the function also includes operations for updating the data of already-registered users based on some conditions.

The function does one of two things:

1. It creates an authentication token for an existing account and returns it after updating the account details or,

2. It creates an account if none exists and returns an authentication token.

This violates the Single Responsibility Principle – but fixing that is a challenge for another article.

The goal here is to refactor this function so that it reads so well that even a non-programmer can read it and understand what it does. Even better, we also want them to be able to remember it after they’ve been away from it for a while.

The function is well-tested, so there are no worries about breaking any functionality while refactoring. Tests will report any breaking changes.

What Makes This Code Hard to Read?

A number of factors make this code harder to read. Here are the main ones:

1. Deep nesting (if statements within if statements) makes it hard to keep track of the changes that occur through the execution of the code. In the case of createOrUpdateUserOnLogin, it is nested conditionals. Other cases can include logic like an if statement inside a while loop which is nested inside another if statement.

   Deep nesting increases the complexity of reading and understanding code. Its flow isn’t pleasant to the eyes and it makes writing tests more complicated because you have to cater for the operations inside the nested code blocks.

2. Complex conditionals like user && !user.photoUrl && dto.photoUrl hold a lot of logic which has to be kept in your short-term memory and remembered as you read on.

3. Haphazard flow which makes it hard for you to tell at a glance what the function is doing. The function seems to be doing a lot, but it really is not. Two operations are repeated: preventing disabled users from logging in (twice) and updating users’ verification status (three times). Finding a user by email is also repeated twice.

How to Refactor the Code for Easier, More Delightful Reading

After examining the function for issues that make it difficult to read, here are a couple of changes you’ll want to implement:

Handle failure cases first: Consider failure cases first and get them out of the story so that the function can focus on the success cases for a smooth narration of the logic of the code.

This involves the use of return statements or throwing errors early in the function for operations that prevent the goal of the function from being achieved.

Rearrange the flow: If it’s possible that some operations can occur before others and it will make the flow of the code memorable and enjoyable to read, while still achieving the purpose of the function, then you should rearrange it accordingly.

Use everyday grammar: This involves updating identifiers and compressing complex conditionals into memorable identifier names. Everyday grammar is easy to read because it is familiar and relatable.

Avoid nested code blocks: When debugging code mentally or trying to understand it, changes in the value of identifiers in nested code blocks are hard to keep track of. This is because with each nested conditional, there is at least a 2x increase in the number of paths that the logic execution can take to update the value of one identifier – and that gets worse if there is more than one identifier that is updated.

This means that your mind has to keep track of those paths which can escalate quickly into a mental memory overload, potentially resulting in mental grief and bugs when updating the code.

The visual effect of nested code is also not pleasant to the eyes and it makes writing tests more complex than it should be.

After refactoring the code using the guidelines above, we have the following snippet (I’ve numbered different parts of the code for reference in the explanations below):

async function updateUserOnLogin(dto) {
  let user = await findUserByEmail(dto.email); // 1
  if (!user) {
    user = await createUser(dto);
  }

  if (user.isDisabled) { // 2a
    throw new Error("Unable to login"); // 2b
  }

  const userIsNotVerified = Boolean(user.isVerified) == false // 3a
  if (userIsNotVerified) { // 3b
    await setUserAsVerified(user.email);
  }

  const shouldUpdateAppleId = dto.loginProvider == "apple" && dto.appleId // 4a
  if (shouldUpdateAppleId) { // 4b
    await setUserAppleId(user.email, dto.appleId);
  }

  const shouldUpdatePhotoUrl = !user.photoUrl && dto.photoUrl // 5a
  if (shouldUpdatePhotoUrl) { // 5b
    await updateUserDetails(user._id, { photoUrl: dto.photoUrl });
  }

  return await this.createToken(user);
}

Alright, now let’s see what exactly we’ve done here to make the code more enjoyable to read.

1. Rearranging the Flow

Judging by the JSDoc comment above the function, email is a required argument field. Existing accounts have an email address irrespective of their login provider. We can fetch an account by email first and decide to create a new one if none exists (code section 1). By doing this, failure cases are handled early.

Choosing to throw an error if the account is disabled at the beginning (section 2b) is also an attempt to handle failure cases early. This does not affect new accounts because new accounts are not disabled by default.

Handling failure cases early helps us understand the code easier because we’re free to consider only what is going to happen without keeping track of error cases from before (like remembering if the user object has a value or not (section 5)) as we read on.

The refactored code has also eliminated nested conditionals and still works as expected.

2. Using Everyday Grammar

In trying to make the code read like everyday grammar, we’ve used clear and relatable variable names (see sections 2a, 3, 4, 5). Written this way, even non-programmers like product managers can read the code and understand what is happening.

Everyday grammar reads like pseudocode - “If user is not verified then set user to verified” and “If should update apple id then update appleId”.

Using everyday grammar is key to making code read like a story.

Conclusion

Code that is delightful to read promotes maintainability and thus, longevity of software. Contributors can read it, understand it, and eventually update it with ease. Like reading a well-written story, reading code can be an enjoyable activity.

Image credit: Work illustrations by Storyset

Now, think about writing messy code – it’s just as confusing, if not more!

On the other hand, clean code is like an organized room: you can easily find what you need, understand what’s happening, and get things done faster.

Let’s have a look at this graph. It shows two different ways of writing code and how they affect the time it takes to add more lines:

1. ⚠️ Quick & Dirty Code (Red line): This is when you write code quickly without planning or organizing it well. At first, it may seem faster, but as more lines are added, it becomes harder to understand and fix. So, over time, it takes longer and longer to add each new line.

2. ⚡ Thoughtful & Clean Code (Blue line): This is when you write code carefully, making it easy to understand and change. At first, it might take a bit longer, but over time, it remains easy to work with. This way, adding new lines doesn't become more difficult.

In simple terms, writing clean code might seem slower at the beginning, but in the long run, it saves a lot of time and makes work easier. It also leads to more reliable software and better products.

Writing clean code is a habit that professional developers cultivate, showing dedication to quality and a strong work ethic. And in this article, I’ll walk you through some best practices for keeping your code clean.

What we’ll cover:

1. Use Meaningful Names

2. Follow the Single Responsibility Principle (SRP)

3. Avoid Unnecessary Comments

4. Make Your Code Readable

5. Write Unit Tests

6. Be Careful with Dependencies

7. Organize Your Project

8. Use Consistent Formatting

9. Avoid Hardcoding Values

10. Limit Function Length

11. Conclusion

10 Essential Tips for Writing Clean Code

To help you get started on your clean code journey, here are 10 practical tips to keep your code readable, organized, and efficient.

1. Use Meaningful Names

When naming variables, functions, and classes, pick names that clearly describe their purpose.

Instead of calling a variable b, try numberOfUsers. This way, anyone reading your code can easily understand its purpose without needing additional comments. A meaningful name eliminates guesswork and avoids confusion.

Example:

// Good
let numberOfUsers = 5; // Clear and easy to understand

// Bad
let b = 5; // Vague and unclear

💡 Naming Tips

• Variables: Use nouns that describe the data, like userAge or totalAmount.

• Functions: Use action words, like calculateTotal() or fetchUserData().

• Classes: Use singular nouns, like User or Order, to represent what they are.

// Variable: Describes the data it holds
let userAge = 25;

// Function: Uses an action word to describe what it does
function calculateTotal(price, quantity) {
    return price * quantity;
}

// Class: Singular noun representing a type of object
class User {
    constructor(name, age) {
        this.name = name;
        this.age = age;
    }
}

2. Follow the Single Responsibility Principle (SRP)

The Single Responsibility Principle means that each function or method should have one specific job.

This keeps your functions short and focused which makes them easier to read, test, and maintain.

Imagine a toolbox where each tool has a unique purpose—clean code functions should work the same way.

For instance, if you have a function called calculateTotal, it should only handle calculating the total. If you add extra tasks, it can lead to confusing code that’s hard to maintain.

Here's an example to show why it's important to keep functions focused:

Let’s say you want to calculate a total and return an object with extra information, like who calculated it and when. Instead of adding these directly into calculateTotal, we can use a second function.

1. Good Example (Separate Tasks)

    // This function only calculates the total
    function calculateTotal(a, b) {
        return a + b;
    }
   
    // This function creates an object with extra details
    function createCalculationRecord(a, b, user) {
        let sum = calculateTotal(a, b); // Calls the calculate function
        return {
            user: user,
            total: sum,
            timestamp: new Date()
        };
    }
   
    let record = createCalculationRecord(5, 10, "Shahan");
    console.log(record);
   

   👍 Why this is good: Each function has a clear, focused task. calculateTotal only does the math, while createCalculationRecord adds the extra details. If you want to change how the total is calculated, you only update calculateTotal, and if you want to change the record format, you only update createCalculationRecord.

2. Bad Example (Mixed Tasks in One Function)

    // This function calculates the total and creates an object in one step
    function calculateTotalAndReturnRecord(a, b, user) {
        let sum = a + b;
        return {
            user: user,
            total: sum,
            timestamp: new Date()
        };
    }
   
    let record = calculateTotalAndReturnRecord(5, 10, "Shahan");
    console.log(record);
   

   👎 Why this is bad: The function name calculateTotalAndReturnRecord shows that it’s trying to do multiple things. If you want to use just the calculation, you can’t reuse this function without the record part. It’s also harder to update and test each task separately.

3. Avoid Unnecessary Comments

Good code should be self-explanatory without needing excessive comments. Focus on writing code that’s clear and understandable on its own.

Comments are helpful when explaining complex logic or a unique approach, but too many comments can clutter your code and make it hard to follow.

💬 When to Use Comments:

• To clarify why something is done in a particular way.

• When working with complex algorithms or calculations.

• To add notes about potential limitations.

Example:

// Clear name, no comment needed
let userAge = 25;

// Unclear name, comment needed
let a; // age of the user

4. Make Your Code Readable

Readable code uses indentation, line breaks, and spaces to keep everything neat and organized.

Think of it like writing a story: paragraphs make reading easier by breaking up large chunks of text. In coding, line breaks serve the same purpose.

Example:

// Good Code
if (isLoggedIn) {
    console.log("Welcome!");
} else {
    console.log("Please log in.");
}

// Bad Code
if(isLoggedIn){console.log("Welcome!");}else{console.log("Please log in.");}

In VS Code, Prettier and Black are popular formatters that automatically apply clean code styling for multiple languages.

PyCharm and IntelliJ have powerful built-in formatters with customizable rules, supporting PEP 8 for Python and other standard guides. These tools ensure consistent, readable code across projects with minimal manual effort.

5. Write Unit Tests

Unit tests help make sure each part of your code works as expected.

By testing small, individual parts (like functions), you can catch bugs early and prevent them from spreading to other parts of the code.

Concretely, unit tests are actually mini quality checks for each part of your code to ensure they’re working as intended.

🍎 Real-world Example:

Let’s look at how to test a complex JavaScript object with multiple methods, using a Calculator class as an example.

This approach will help you see why it’s important to keep each method focused on one task and ensure each one works correctly through unit testing.

Here is the Calculator class that includes methods for basic arithmetic operations: addition, subtraction, multiplication, and division.

class Calculator {
    constructor() {
        this.result = 0;
    }

    add(a, b) {
        return a + b;
    }

    subtract(a, b) {
        return a - b;
    }

    multiply(a, b) {
        return a * b;
    }

    divide(a, b) {
        if (b === 0) throw new Error("Cannot divide by zero");
        return a / b;
    }
}

As you can see, each method performs one specific operation. The divide method has additional logic to handle division by zero, which would otherwise cause an error.

Now, we’ll write unit tests to confirm that each method behaves as expected. 🔬

🧪 Writing Unit Tests for Each Method

To test our Calculator class, we can write unit tests that cover normal cases as well as edge cases. Here’s how we would set up tests for each method:

// Initialize the Calculator instance
const calculator = new Calculator();

// Test add method
console.assert(calculator.add(2, 3) === 5, 'Test failed: 2 + 3 should be 5');
console.assert(calculator.add(-1, 1) === 0, 'Test failed: -1 + 1 should be 0');

// Test subtract method
console.assert(calculator.subtract(5, 3) === 2, 'Test failed: 5 - 3 should be 2');
console.assert(calculator.subtract(0, 0) === 0, 'Test failed: 0 - 0 should be 0');

// Test multiply method
console.assert(calculator.multiply(2, 3) === 6, 'Test failed: 2 * 3 should be 6');
console.assert(calculator.multiply(-1, 2) === -2, 'Test failed: -1 * 2 should be -2');

// Test divide method
console.assert(calculator.divide(6, 3) === 2, 'Test failed: 6 / 3 should be 2');
try {
    calculator.divide(1, 0);
    console.assert(false, 'Test failed: Division by zero should throw an error');
} catch (e) {
    console.assert(e.message === "Cannot divide by zero", 'Test failed: Incorrect error message for division by zero');
}

🫧 Explanation of the tests:

1. Addition (add method): We test that add(2, 3) returns 5, and add(-1, 1) returns 0. If these tests pass, we know that the addition logic is working correctly.

2. Subtraction (subtract method): We verify that subtract(5, 3) returns 2, and subtract(0, 0) returns 0. These checks confirm that subtraction is accurate.

3. Multiplication (multiply method): We test the multiplication function with both positive and negative values, ensuring that multiply(2, 3) returns 6, and multiply(-1, 2) returns -2.

4. Division (divide method): We verify that dividing 6 by 3 returns 2. For division by zero, we use a try...catch block to confirm that an error is thrown with the correct message. This test make sure the method handles errors properly.

You can see that if any method fails, the test will produce a clear error message, allowing us to quickly identify and fix the issue. Testing methods individually helps us catch bugs early and maintain reliable, clean code as the project grows.

6. Be Careful with Dependencies

Dependencies are pieces of software that your code relies on. 🔌

Imagine you’re building a web app that sends emails. Instead of writing the email-sending code yourself, you use an external library like Nodemailer. Here, Nodemailer is a dependency—your app relies on it to handle the email-sending functionality.

Example:

const nodemailer = require('nodemailer');

function sendEmail(to, subject, message) {
    const transporter = nodemailer.createTransport({
        service: 'gmail',
        auth: {
            user: 'your-email@gmail.com',
            pass: 'your-email-password'
        }
    });

    const mailOptions = {
        from: 'your-email@gmail.com',
        to: to,
        subject: subject,
        text: message
    };

    return transporter.sendMail(mailOptions);
}

In this code, nodemailer is imported and used to create a transporter for sending emails. Without it, you’d need to build all the email functionality from scratch, which would be complex and time-consuming. By using Nodemailer as a dependency, your app can send emails easily.

Even though dependencies are useful, you should try to avoid over-dependence on external software or libraries. Use dependencies only when they simplify your work or add important functionality.

Managing dependencies effectively is key to writing clean code. Here are some tips:

• Limit Dependencies: Only include libraries or modules that are essential for your project.

• Keep Versions Updated: Use updated versions of libraries to avoid security risks.

• Separate Logic: Write core functions yourself whenever possible. This way, if you ever need to remove a dependency, it won’t break your code.

Let me give you an example with our previous Nodemailer code to implement the concept of separating logic in your code.

You can create a wrapper function that abstracts away the details of email sending. This way, you can change the underlying email service or remove the dependency on Nodemailer without affecting the rest of your code.

Here's how you can structure your code to accomplish this:

const nodemailer = require('nodemailer');

// Core function to send email
function sendEmail(to, subject, message) {
    const transporter = createTransporter();
    const mailOptions = createMailOptions(to, subject, message);
    return transporter.sendMail(mailOptions);
}

// Function to create the transporter
function createTransporter() {
    return nodemailer.createTransport({
        service: 'gmail',
        auth: {
            user: 'your-email@gmail.com',
            pass: 'your-email-password'
        }
    });
}

// Function to create mail options
function createMailOptions(to, subject, message) {
    return {
        from: 'your-email@gmail.com',
        to: to,
        subject: subject,
        text: message
    };
}

// Example usage
sendEmail('recipient@example.com', 'Test Subject', 'Hello, this is a test email.')
    .then(() => {
        console.log('Email sent successfully!');
    })
    .catch((error) => {
        console.error('Error sending email:', error);
    });

🗝️ Key points:

1. Core Functions: The sendEmail, createTransporter, and createMailOptions functions are separate, allowing you to modify one without affecting the others.

2. Easy Modifications: If you want to switch to another email service in the future, you can simply modify the createTransporter function.

3. Maintainability: This structure makes your code more maintainable and easier to understand.

7. Organize Your Project

A well-organized project structure is as important as the code itself.

Think of this like organizing your workspace—you need designated places for everything so that you can find them easily. For coding projects, create folders for specific parts, like components, utils, and services.

📂 How to Organize Your Project

To set up a clean and organized project, you should categorize different parts of your code into designated folders. Here’s a simple example of what a well-organized project structure might look like:

myProject
├── src
│   ├── components
│   ├── services
│   ├── utils
└── tests

Breakdown of the project structure:

1. myProject: This is the root folder of your project. It contains everything related to your application.

2. src (Source): This folder holds all the source code for your project. It’s where you’ll spend most of your time coding.

3. components: This subfolder contains reusable UI components. For example, if you're building a web app, you might have individual files for buttons, headers, or forms here. Each component can be in its own file to keep things modular.

   • Example structure within components:

    components
    ├── Button.js
    ├── Header.js
    └── Form.js

4. services: This folder includes functions that perform specific tasks or handle business logic. For example, if you're sending emails, you could have a file here with all the email-related functions.

   • Example structure within services:

    services
    ├── emailService.js
    ├── userService.js
    └── productService.js

5. utils (Utilities): Here, you place helper functions that can be used across your project. These might include functions for formatting dates, validating inputs, or any other common tasks that don't belong to specific components or services.

   • Example structure within utils:

    utils
    ├── formatDate.js
    ├── validateEmail.js
    └── generateId.js

6. tests: This folder is dedicated to your testing files. Keeping your tests organized helps ensure that as you build new features, you can easily test them without digging through your codebase.

   • Example structure within tests:

    tests
    ├── emailService.test.js
    ├── userService.test.js
    └── component.test.js

📨 Real-World Example: Working with Nodemailer

Let's say you are building an application that sends emails to users. You might structure your project like this:

myEmailApp
├── src
│   ├── components
│   │   ├── EmailForm.js
│   │   └── SuccessMessage.js
│   ├── services
│   │   └── emailService.js
│   ├── utils
│   │   └── validateEmail.js
└── tests
    ├── emailService.test.js
    └── EmailForm.test.js

• EmailForm.js: This component handles the user interface for sending an email, like the input fields for the recipient, subject, and message.

• SuccessMessage.js: This component displays a success message once the email has been sent.

• emailService.js: This service contains the logic for sending emails using Nodemailer, keeping your code modular and clean.

• validateEmail.js: A utility function that checks if an email address is formatted correctly.

• tests: Here, you would write tests to ensure your email service and components are functioning as expected.

🍱 Benefits of a Well-Organized Project

1. Ease of Navigation: Anyone looking at your project can quickly understand where to find specific parts of the code.

2. Better Collaboration: If you’re working with others, a clear structure helps everyone know where to contribute without stepping on each other’s toes.

3. Scalability: As your project grows, maintaining a clear structure helps manage the complexity and keeps your codebase clean.

4. Improved Maintenance: When you need to update or fix something, you can find the relevant files quickly, which saves time and reduces errors.

8. Use Consistent Formatting

Consistency in formatting improves readability.

Establish a pattern for how you write your code, such as using two spaces for indentation or always including a line break before comments.

Following consistent formatting makes your code look clean and well-organized.

🛠️ Tools for Formatting

• Prettier: Automatically formats code based on a set of rules. Here’s a tutorial that explains how to set up and use Prettier in VSCode.

• ESLint: Helps enforce coding standards by highlighting issues. Here’s a tutorial that includes a helpful and in-depth section on setting up ESLint for your projects.

9. Avoid Hardcoding Values

Hardcoding is directly embedding data values in code, like setting a user ID as 123 instead of using a variable.

Avoiding hardcoded values allows you to reuse code without making constant changes. Store values in variables, constants, or configuration files instead.

Here’s a scenario where hardcoding can lead to issues:

// Bad: Hardcoding user limit
function createUser(name) {
    let numberOfUsers = 100; // Hardcoded value
    if (numberOfUsers >= 100) {
        return 'User limit reached.';
    }
    // Code to create the user
    return 'User created.';
}

In this example, numberOfUsers is hardcoded to 100. If you want to change the user limit, you have to find and modify this value in the code. If it appears in multiple places, this task becomes cumbersome and error-prone.

🏗️ Improved Example Using Constants

Now, let’s refactor this code to use a constant instead:

// Good: Using a constant
const MAX_USERS = 100; // Store the limit in a constant

function createUser(name) {
    let numberOfUsers = getCurrentUserCount(); // Get the current count from a function or database
    if (numberOfUsers >= MAX_USERS) {
        return 'User limit reached.';
    }
    // Code to create the user
    return 'User created.';
}

// Example function to get current user count
function getCurrentUserCount() {
    // Simulate fetching the current count, e.g., from a database
    return 90; // Example count
}

🥣 Breakdown of the improved example:

1. Using Constants: The MAX_USERS constant is defined at the top. This way, if you ever need to change the maximum number of users, you only have to update it in one place.

2. Dynamic Values: The getCurrentUserCount() function dynamically retrieves the current user count from a database or any other source. This approach prevents hardcoding the count and allows for easy changes.

3. Maintainability: By storing values in constants, your code becomes more maintainable. If the business requirement changes and you need to increase the user limit to 150, you can simply change MAX_USERS from 100 to 150, and the change will reflect throughout your application.

4. Clarity: Using descriptive names for your constants (like MAX_USERS) improves the readability of your code. Anyone looking at your code can quickly understand what this value represents.

🤐 When to Use Configuration Files

In larger applications, you might also consider using configuration files (like JSON, YAML, or environment variables) to store values that may change between environments (development, staging, production).

For instance in your config.json file you can hardcode maxUsers as follows (keep in mind that in config.json, its recommended to use camelCase as it follows consistent formatting):

{
    "maxUsers": 100,
    "emailService": {
        "service": "gmail",
        "user": "your-email@gmail.com",
        "pass": "your-email-password"
    }
}

🪴 Using Configuration in Your Code:

const config = require('./config.json');

function createUser(name) {
    let numberOfUsers = getCurrentUserCount(); 
    if (numberOfUsers >= config.maxUsers) {
        return 'User limit reached.';
    }
    // Code to create the user
    return 'User created.';
}

10. Limit Function Length

Long functions are harder to understand and maintain.

There’s no strict rule, but in general, functions should ideally be no more than 20-30 lines. If a function has multiple responsibilities or contains many steps, that’s a good indication it might be too long. Breaking down these functions into smaller "helper" functions can make them more manageable and understandable.

Here’s what a long, complex function might look like:

function updateCart(cart, item, discountCode) {
    // Add the item to the cart
    cart.items.push(item);

    // Calculate the new total
    let total = 0;
    cart.items.forEach(cartItem => {
        total += cartItem.price * cartItem.quantity;
    });

    // Apply discount if available
    if (discountCode) {
        total = applyDiscount(total, discountCode);
    }

    // Log the transaction
    console.log(`Item added: ${item.name}, New total: $${total}`);

    return total;
}

⚠️ This function does multiple things:

1. Adds an item to the cart.

2. Calculates the total price.

3. Applies a discount if there’s a code.

4. Logs the transaction.

While this function might look manageable now, it can quickly grow if more tasks are added, making it harder to debug and maintain.

Let’s break this long function into smaller, single-purpose functions:

function updateCart(cart, item, discountCode) {
    addItemToCart(cart, item);
    let total = calculateTotal(cart);

    if (discountCode) {
        total = applyDiscount(total, discountCode);
    }

    logTransaction(item, total);
    return total;
}

function addItemToCart(cart, item) {
    cart.items.push(item);
}

function calculateTotal(cart) {
    return cart.items.reduce((total, cartItem) => total + cartItem.price * cartItem.quantity, 0);
}

function logTransaction(item, total) {
    console.log(`Item added: ${item.name}, New total: $${total}`);
}

🧩 Let me explain:

1. addItemToCart: This function is now responsible only for adding an item to the cart. It’s simple, with a clear purpose.

2. calculateTotal: This function calculates the total price of all items in the cart. It’s easier to read and understand, and if you need to update the way totals are calculated, you only have to modify this function.

3. logTransaction: Handles the responsibility of logging details. If you ever need to change what gets logged (for example, adding a timestamp), you can do so in this function without touching the rest of the code.

4. updateCart: The main function now reads more like a summary of the actions being taken: add an item, calculate the total, apply discounts, and log the result. It’s easier to follow and understand at a glance.

📒 Let’s summarize limiting function length:

1. 🎯 Focus on One Task: Each function should ideally perform just one task. If a function seems to be doing multiple tasks, consider breaking it up.

2. 🩼 Use Helper Functions: Helper functions are small, focused functions that assist a main function by performing a specific task. In the example above, addItemToCart, calculateTotal, and logTransaction are helper functions.

3. 🪦 Descriptive Names: Name your functions based on their tasks (for example, addItemToCart), which helps make the code self-explanatory.

Best Practices for Clean Code

Now that we’ve covered some important tips, let’s look at some overarching principles that make up the philosophy behind clean code:

1. 🎏 Simplicity: Always aim to make your code as simple as possible.

2. 🧂 Consistency: Keep your code uniform in style and structure.

3. 🌾 Clarity: Your code should clearly communicate what it does.

4. ⛽ Efficiency: Write code that’s optimized for performance without sacrificing readability.

These principles make coding less about writing and more about designing solutions. Writing clean code is a skill that grows with practice, so keep learning and improving over time.

🔌 A Note on Dependencies

Instead of hardcoding dependencies directly into your code, use package managers like npm (for JavaScript) or pip (for Python) to manage them. This way, you can easily update or remove them when needed.

Conclusion 🏁

Writing clean code is like building a strong foundation for a house. It keeps everything in order, making it easy to add new features or fix issues as your project grows.

With these tips, you can start developing habits that will make your code more readable, maintainable, and enjoyable to work on.

Recommended Next Steps 📘

For a structured guide to becoming a backend developer in six months, you can check out my backend developer roadmap. It’s designed to help beginners stay on track with weekly goals, covering the essential skills, tools, and technologies. This roadmap can keep you motivated and make learning more manageable.

You can follow me on 𝕏 for instant updates.

Hope to see you next time!

To get the most out of this guide, you should have a background in JavaScript, understand how Mongoose works, and know Object-Oriented Programming basics.

Here's what we'll cover:

1. What is a Mongoose Schema?

2. Discriminator

3. Statics

4. Methods

5. Query Builder

6. Hooks

7. Summary

What is a Mongoose Schema?

Mongoose schemas provide a structured way to model data in a MongoDB database, allowing you to define the properties and behavior of the documents. Schemas serve as a blueprint for a document that gets saved in the database. They enables developers to enforce data integrity and work with MongoDB in a more intuitive and organized manner.

Within a MongoDB collection, a schema outlines the fields of the documents, their data types, validation rules, default values, constraints, and more.

Programmatically, a Mongoose schema is a JavaScript object. Actually, it is an instance of a built-in class called Schema inside the mongoose module. For this reason, you can add more methods to its prototype. This will help you implement many features as middleware, methods, statics, and more. You will learn about some of them in this tutorial.

Features you'll learn how to implement:

• Discriminator

• Statics

• Methods

• Query Builder

• Hooks

Discriminator

A discriminator is a feature that enables you to create multiple models (subtypes) that inherit from a base model (parent). This happens by defining a base schema and then extending it with extra fields specific to each subtype or each child schema.

All documents, regardless of their specific model, are stored in the same MongoDB collection. This keeps your data organized in a single collection while allowing for flexible querying and data management. Also, each document includes a special field that indicates its specific model type, allowing Mongoose to distinguish between the different subtypes.

How to use discriminator:

1. Start by defining a base schema, which will have the common fields among the subtypes. After that, create a model from it.

    import mongoose from 'mongoose';
   
    const baseSchema = new mongoose.Schema({
        name: { type: String, required: true },
    }, { discriminatorKey: 'kind' }; // defaults to '__t');
   
    const BaseModel = mongoose.model('Base', baseSchema);
   

2. Create the subtypes that extend the base schema by defining the discriminator for each one.

    const catSchema = new mongoose.Schema({
        meow: { type: Boolean, default: true }
    });
    // subtype
    const Cat = BaseModel.discriminator('Cat', catSchema);
   
    const dogSchema = new mongoose.Schema({
        bark: { type: Boolean, default: true }
    });
    // subtype
    const Dog = BaseModel.discriminator('Dog', dogSchema);
   

3. You can then create documents in the regular way. All the documents will be stored in the same collection, but each has its own type depending on its subtype model.

    const fluffy = await Cat.create({ name: 'Fluffy' });
    const rover = await Dog.create({ name: 'Rover' });
   

discriminator use case:

Let's say that you're building a multi-user Ecommerce web application which accommodates three main user roles: admins, clients, and sellers. Each of these roles plays a crucial part in the ecosystem of online shopping.

If you try to build a class for each role, you'll find that all the three have common fields and methods. You may decide to create a parent schema (user) and some other children schemas (client, seller, admin) that inherit from it.

You can use the discriminator to achieve this.

In your user.model.js file, add the following code:

import mongoose from "mongoose";

const userSchema = mongoose.Schema(
  {
    name: String,
    profilePic: String,
    email: String,
    password: String,
    birthDate: Date,
    accountAcctivated: { type: Boolean, default: false },
  },
  {
    timestamps: true,
    discriminatorKey: "role",
  }
);

const User = mongoose.model("User", userSchema);
export default User;

Now you have the base model (User) from which other subtypes will inherit. In this parent schema, you define the common fields that all users will share regardless of their roles.

In your client.model.js file:

import mongoose from "mongoose";
import User from "./user.model.js";

const clientSchema = mongoose.Schema(
  {
    products: Array,
    address: String,
    phone: String,
  }
);

const Client = User.discriminator("Client", clientSchema);
export default Client;

In your seller.model.js file:

import mongoose from "mongoose";
import User from "./user.model.js";

export const sellerSchema = mongoose.Schema(
  {
    rating: Number,
    businessType: { type: String, enum: ["individual", "corporation"] },
  }
);

const Seller = User.discriminator("Seller", sellerSchema);
export default Seller;

In your admin.model.js file:

import mongoose from "mongoose";
import User from "./user.model.js";

export const adminSchema = mongoose.Schema(
  {
    permissions: Array,
    assignedTasks: Array,
    department: String,
  }
);

const Admin = User.discriminator("Admin", adminSchema);
export default Admin;

The subtypes or children will be the Client, Seller, and Admin. In each subtype schema, you should add any extra fields or behaviors specific to this subtype only. By creating the child model using the discriminator, the child model will inherit all the fields and methods of its parent model User.

So the previous code will create a user collection in the database with each document having a role field either Client, or Seller, or Admin. All documents are now sharing the parent (user) fields, and depending on the role of each document, each has another extra field.

Although all the documents will be saved in one single collection, models are fully separated while coding. What does this mean?

For instance, If you need to retrieve all clients from the User collection, you should write Client.find({}). This statement uses the discriminator key to find all documents whose role is Client. This way, any operations or queries that refer to one of the child models will still be written separately from the parent model.

Note: Before diving into the next sections, just keep in mind that any statics, methods, query builders, or hooks should be defined before creating the model itself (that is, before const User = mongoose.model("User", userSchema);).

Statics

Statics are useful for defining functions that operate on the model level. They allow you to define reusable functions for operations related to the entire model. They help encapsulate logic that applies to the model rather than individual documents, making your code cleaner, more organized and maintainable

Methods like find, findOne, findById and others all are methods attached to the model. By using the statics property of Mongoose schemas, you will be able to build your own model method.

Statics are powerful. By using them, you can encapsulate complex queries that you might want to reuse. Also, you can create statics for operations that modify or aggregate data, such as counting documents or finding documents based on specific criteria.

statics use case

Statics are easy to build. You define a static method on your schema using the statics object.

In your user.model.js file, add these static methods, countUsers and findByEmail:

// model method
userSchema.statics.countUsers = function () {
    return this.countDocuments({});
};

// model method
userSchema.statics.findByEmail = async function (email) {
  return await this.findOne({ email });
};

Inside any static method, this refers to the model itself. In this example, this in this.findOne({ email }) refers to the User model.

Example usage:

const user = await User.findByEmail("foo@bar.com");
//or
const client = await Client.findByEmail("foo@bar.com");
//or
const seller = await Seller.findByEmail("foo@bar.com");
//or
const admin = await Admin.findByEmail("foo@bar.com");

When you call the static method on your model, the method gets called and this is replaced by the model you called the statics on. This line performs a query to find a single document in the MongoDB collection where the email field matches the provided email argument.

Methods

Methods are functions that you can define on a schema and that can be called on instances of documents created from this schema. They help encapsulate logic within the document itself, making your code cleaner and more modular.

By using instance methods, you can easily interact with and manipulate the data associated with specific documents.

methods use case

You can define methods on the schema using the methods object.

In your user.model.js file, add a document method through which you can check the password of a user:

// instance or document method
userSchema.methods.getProfile = function () {
    return `${this.name} (${this.email})`;
};

// instance or document method
userSchema.methods.checkPassword = function (password) {
    return password === this.password ? true : false;
};

Inside any document method, this refers to the document itself. In this example, this in this.password refers to the user document at which the method will get called on. This means that you can access all the fields of this document. This is so valuable because you can retrieve, modify, and check for anything related to this document.

Example usage:

const client = await Client.findById(...)
client.checkPassword("12345")
//or
const seller = await Seller.findById(...)
seller.checkPassword("12345")
//or
const admin = await Admin.findById(...)
admin.checkPassword("12345")

Since methods are instance-level functions, they are called on the documents. await Client.findById(...) will return a document that has all the built-in methods as well as your own predefined methods checkPassword and getProfile. So by calling, for example client.checkPassword("12345"), the this keyword in the checkPassword function definition will get replaced with the client document. This in turn will compare the user password with the password saved earlier in the database.

Query Builder

A query builder in Mongoose is a custom method that you can define on the query object to simplify and encapsulate common query patterns. These query builders allow you to create reusable and readable query logic, making it easier to work with your data.

One of the most valuable usages of query builders is chaining. They can be chained with other query builders that you've built or with standard query methods like find, sort, and so on.

Query builder use case

You define query builders by adding them to the query property of a Mongoose schema.

In your user.model.js file, add a query helper method that lets you implement pagination.

// query helper
userSchema.query.paginate = function ({ page, limit }) {
    // some code
    const skip = limit * (page - 1);
    return this.skip(skip).limit(limit);
};

To implement pagination, you need two important variables: first, the page number, and second, the number of items you will retrieve per page.

To query the database for a specific count of documents, you will always use the skip and limit built-in query methods in mongoose. skip is used to set a cursor after a certain number of documents, after which the query will get implemented. limit is used to retrieve a specific number of documents.

Inside any query builder method, this refers to the query itself. And since query builders are chainable, you can call any of them after each other.

Finally, any query builder method should return a mongoose query object, which is why you must write return this.skip(skip).limit(limit).

Example usage:

const results = await Client.find().paginate({ page: 2, limit: 5 });
//or
const results = await Seller.find().paginate({ page: 2, limit: 5 });
//or
const results = await Admin.find().paginate({ page: 2, limit: 5 });

You can then call it on any query, and await Client.find().paginate({ page: 2, limit: 5 }) will invoke the paginate function and replace the this keyword with Client.find() using the query builder.

You can implement pagination with certain conditions, but you'll always call skip and limit. By defining the paginate query builder you won't repeat yourself and you'll be able to encapsulate the logic in one single function.

Hooks

Hooks (also known as middleware) are functions that are executed at specific points in the lifecycle of a document. They allow you to add custom behavior before or after certain operations, such as saving, updating, or removing documents.

Types of Hooks

• Pre Hooks: Executed before an operation.

• Post Hooks: Executed after an operation.

Hooks use case

In your user.model.js file, add a post save middleware through which you can send an email for account activation once the user document is saved in the database.

// post hook
userSchema.post("save", async function (doc, next) {
  // send email logic
  // if succeeded
  return next();
  // if failed
  return next(new Error("Failed to send email!"));
});

The callback function will get invoked once you create a user through model.create() or any time you call save() method on the user document.

In this this example, if you need to avoid sending emails on save, you should write a condition to be sure that this save is for a new user only. You can write something like if (doc.createdAt.getTime() === doc.updatedAt.getTime()).

Summary

In this overview of Mongoose features, we've explored four key concepts: discriminators, statics, methods, and hooks.

Discriminators allow you to create multiple models that share a common schema enabling different document types to be stored in a single collection. This facilitates data management and querying.

Statics are model-level methods that provide reusable functionality applicable to the entire model. They encapsulate complex queries and data manipulation logic, helping to keep your codebase clean and maintainable.

Methods are instance-level functions that operate on individual document instances. They allow for custom behaviors and data manipulations specific to each document, so you can modify the document’s data in a specific way, such as formatting or calculating values based on its fields.

Hooks (or middleware) enable you to run functions at specific points in the document lifecycle, such as before or after saving, updating or deleting a document. This is useful for implementing validation, logging, or any other side effects related to database operations.

Together, these features enhance the versatility and organization of your Mongoose models, making it easier to build robust and maintainable applications with MongoDB.

Here can will find a repository where you can learn more about Mongoose schemas and use cases.

If your answer to all or most of these is a string, then you are suffering from what Software Development experts call "Primitive Obsession".

While primitives like int, char, byte, short, long, float, double, boolean, strings, and so on are the basic built-in building blocks of any programming language, Primitive Obsession is when your code relies too much on them to represent otherwise more complex concepts.

Experts say it's a code smell. This is because Primitive Obsession can lead to a range of problems including lack of validation, poor readability, code duplication, and difficulty in refactoring. This article will help you resolve this issue.

What You'll Learn in this Article

This tutorial, while quite short, is designed to help you understand and address the issue of primitive obsession in your code. So when you are done reading, you should be able to:

1. Identify what's so bad about Primitive Obsession and associated drawbacks.

2. Design better software and implement data structures that enhance code correctness, maintainability, and future-proof your software against potential issues.

3. Improve Data Safety, and Security, and reduce the likelihood of runtime errors and unexpected behavior by using more robust data representations.

Prerequisites: What You Need to Know

1. Familiarity with OOP principles like classes, objects, encapsulation, inheritance, and polymorphism will be beneficial when designing custom data structures.

2. Proficiency in statically-typed languages like Java, C#, Go, TypeScript, and Dart where variable types are declared at compile time.

It's fine if you're not familiar with these concepts – there are many resources available online and in textbooks to help you get started. But this tutorial assumes a basic grasp of these foundations and builds upon them to address the issue of primitive obsession.

What's Bad about Primitive Obsession?

Primitive obsession is problematic for several reasons:

1. Weak type checking

2. Limited built-in functionality for specific data types

3. Reduced maintainability and loss of domain knowledge

Let's take a look at each issue in detail:

1. Primitives offer weak type checking

Beyond efficient memory allocation, or wasteful compute time in deciphering what type a value is, one of the benefits of statically type language is that it lets the compiler help you catch potential type mismatches at compile time. This can help prevent runtime errors caused by using the wrong data type.

The compiler would scream at you if you did this:

String phoneNumber = "+1-555-229-1234";
int zipCode = 101257;

zipCode = phoneNumber; // throws an error

What if you did this?

String phoneNumber = "+1-555-229-1234";
String zipCode = "1000 AP"

zipCode = phoneNumber; //works fine

It will compile and do nothing!

Why?

Because a string will always be a string.

The compiler cannot differentiate whether the string value you pass represents a user password or an email address. Consequently, it cannot prevent you from mistakenly assigning a variable to the wrong field leading to runtime errors and unexpected behaviour.

2. Limited built-in functionality for specific data types.

When you rely heavily on primitives, you often need to write additional code to perform tasks such as email address validation or phone number formatting. And that's not a problem really.

The real problem is the repetitive and scattered nature of these implementations. This doesn't just increase the risk of errors but it also makes the code harder to maintain and refactor.

3. Reduced Maintainability and Loss of Domain Knowledge

Scattering business rules and logic across the codebase makes it harder to maintain and evolve the software. When primitives are used extensively, it can be challenging to understand the purpose and constraints of the data they represent.

Encapsulating this logic within dedicated types helps preserve domain knowledge and makes the code more intuitive for future developers.

For instance, you might need to block certain email addresses due to fraud or restrict specific zip codes, areas, or companies. When you use primitives, this important context is not evident, leading to potential errors and increased maintenance burden.

How to Break Away from Primitive Obsession

1. Watch out for variables with special validation logic.

Take Phone Numbers, for example. In Nigeria, where I'm from, all phone numbers are eleven digits long and start with a zero. The second digit is usually a "7" , "8", or "9" which helps identify the telecom operator. Any other number is invalid.

The same can be said for a Website URL. It could very well be represented by a string. But a URL has more information and specific properties compared to a string (for example, the scheme, query parameters, and protocol). And each part has a different validation method.

2. Watch out for variables with special comparison rules

Beyond simple equality checks (==), if you find yourself implementing custom comparison logic for a variable without encapsulating it in a class, it's a red flag.

For instance, comparing email addresses often involves more than a simple equality check. You might need to perform case-insensitive matching, strip out whitespace, or handle variations in formatting to accurately identify matching emails such as + sign in email addresses for people who want to game your ssytem.

daniel@example.com is the same email address as daniel+dev@example.com. Emails sent to the latter will be received on the former.

3. Watch out for variables with special formatting rules

Any variable that requires specific formatting or parsing to extract meaningful information is a candidate for a richer representation.

Currency values are a good example of this. Different regions use different formatting rules – some use commas and some use decimal points. It's the same case with a date of birth or anything that requires some data.

Identifying and resolving primitive obsession is a continuous process.

You won't be able to catch all instances at once, especially those that are uncommon and unique to your business domain. That's perfectly fine – that's how it should be.

Instead of panicking or giving up, gradually refactor your code to incorporate these changes. This approach is key to making your code future-proof and maintainable.

You Don't See it Until You Are Shown

Primitive obsession hides in plain sight. And that's a significant issue because, unlike static errors, linters won't flag them and neither will your program crash as a result.

It often takes a mentor, a code review, or an "aha" moment to realize that these repetitive checks and rules scattered throughout your codebase can be centralized into their own dedicated types. This recognition is the first step toward more robust, readable, and maintainable code.

So stay open-minded, engage with others, read code from different sources, and contribute to open-source projects. That's how you learn. Ultimately, it's all about one thing: encapsulation – grouping data and the methods that operate on it in one location for maintainability.

Credits and resources:

1. A Code Smell that Hurts People the Most by Arpit Jain.

2. Signs and Symptoms of Primitive Obsession by Refactoring Guru.

3. How to Fix Primitive Obsession by Sam Walpole on Hackernoon.

While most developers are familiar with basic console logging using console.log(), there are many other powerful methods provided by the console object that can make debugging more efficient and effective.

In this comprehensive guide, we will explore various console logging tricks such as console.table, console.group, console.assert, and more. These tricks can help you organize your debugging process, visualize complex data structures, and catch errors early on in your development workflow.

Table of Contents

1. Introduction to Console Logging
2. Basic Console Logging
3. Advanced Console Logging Tricks
   – [console.table](#heading-31-consoletable)
   – console.group and console.groupCollapsed
   – [console.assert](#heading-33-consoleassert)
   – console.count and console.countReset
   – console.time and console.timeEnd
   – [console.trace](#heading-36-consoletrace)
   – [console.dir](#heading-37-consoledir)
   – [console.clear](#heading-38-consoleclear)
4. Best Practices for Console Logging
5. Conclusion

1. Introduction to Console Logging

Console logging is a technique used by developers to output messages, variables, and other information to the browser's console. This is particularly useful for debugging purposes, as it allows developers to inspect the state of their code and track its execution flow.

The console object in JavaScript provides various methods for logging different types of information. While console.log() is the most commonly used method, there are several other methods that can be used to enhance your debugging experience.

2. Basic Console Logging

Before we dive into the advanced console logging tricks, let's start by revisiting the basics of console logging using console.log(). This method accepts any number of arguments and outputs them to the console.

const name = "Femi";

const age = 30;

console.log("Name:", name, "Age:", age);

In the above example, we are logging the name and age variables to the console using console.log(). This will output:

Name: Femi Age: 30

You can use console.log() to log strings, numbers, booleans, objects, arrays, and more.

3. Advanced Console Logging Tricks

3.1 console.table

The console.table() method allows you to display tabular data in the console. It takes an array or an object as input and presents it as a table.

const users = [

{ name: "Chris", age: 25 },

{ name: "Dennis", age: 15 },

{ name: "Victor", age: 17 }

];

console.table(users);

The above code will output a table in the console:

(index)  |  name  |  age
-------------------------
0    |  Chris  |   25
1    |  Dennis |   15
2    |  Victor |   17

console.table() is particularly useful when dealing with arrays of objects or other tabular data structures.

3.2 console.group and console.groupCollapsed

The console.group() and console.groupCollapsed() methods allow you to group related log messages together in the console. This can help organize your debugging output and make it easier to understand.

// Start a new console group named "Group 1"
console.group("Group 1");

// Log messages inside "Group 1"
console.log("Message 1");
console.log("Message 2");

// End "Group 1"
console.groupEnd();

// Start a new collapsed console group named "Group 2"
console.groupCollapsed("Group 2");

// Log messages inside "Group 2"
console.log("Message 3");
console.log("Message 4");

// End "Group 2"
console.groupEnd();

In the above example, we create two groups of log messages. The first group is expanded, while the second group is collapsed by default. This helps keep the console output organized and easy to navigate.

If you run this code in a browser's developer console, the output will look something like this:

Group 1
  Message 1
  Message 2
Group 2
  ▶ Message 3
  ▶ Message 4

In this example, "Group 1" is expanded by default, showing the messages inside it. On the other hand, "Group 2" is collapsed initially (indicated by the ▶ symbol), and you need to click on it to expand and reveal the messages inside. The collapsing of "Group 2" makes it visually neater in the console, especially when dealing with a large number of log messages.

3.3 console.assert

The console.assert() method allows you to assert whether a condition is true or false. If the condition is false, it will log an error message to the console.

const x = 5;

// Check if the condition x === 10 is true, if not, log the error message
console.assert(x === 10, "x is not equal to 10");

In this case, the condition being checked is x === 10, which compares the value of the variable x to 10. Since the value of x is 5, the condition is false. As a result, the console.assert method will log the error message to the console.

If you run this code in a browser's developer console, you would see an assertion error in the console output with the specified error message:

Assertion failed: x is not equal to 10

This is a helpful way to include runtime checks in your code and log informative messages if certain conditions are not met.

3.4 console.count and console.countReset

The console.count() method allows you to count the number of times a particular piece of code is executed. You can also reset the count using console.countReset().

function greet() {
  // Log and count the number of times "greet" is called
  console.count("greet");

  // Return a greeting message
  return "Hello!";
}

// Call greet() two times
greet();
greet();

// Reset the counter for "greet"
console.countReset("greet");

// Call greet() again
greet();

console.count("greet");: This line logs the number of times "greet" is called. The count is initially 1 when greet() is first called and increments with each subsequent call.

If you run this code in a browser's developer console, the output might look like this:

greet: 1
greet: 2
greet: 1

The first two calls to greet increment the count, and the third call, after the reset, starts the count again from 1. The count is specific to the label "greet."

3.5 console.time and console.timeEnd

The console.time() and console.timeEnd() methods allow you to measure the time taken by a block of code to execute.

console.time("timer");

for (let i = 0; i < 1000000; i++) {

// Some time-consuming operation

}

console.timeEnd("timer");

In the above example,

• console.time("timer");: This starts a timer with the label "timer" when the loop
• console.timeEnd("timer");: This stops the timer labeled "timer" and logs the elapsed time to the console.

If you run this code in a browser's developer console, the output will look like this:

timer: XXms

The "XX" will be replaced with the actual time taken by the loop to execute the time-consuming operation. This measurement is useful for profiling and understanding the performance of a specific code block or operation.

3.6 console.trace

The console.trace() method outputs a stack trace to the console. This can be helpful for debugging purposes to see the call stack leading to the current execution point.

function foo() {
  // Call the bar function
  bar();
}

function bar() {
  // Log a trace of the call stack
  console.trace("Trace:");
}

// Call the foo function
foo();

• foo function: Calls the bar function.
• bar function: Logs a trace of the call stack using console.trace.
• foo is called: This triggers the call to bar, and the trace is logged.

If you run this code in a browser's developer console, the output might look something like this:

Trace:
bar @ (index):8
foo @ (index):3
(anonymous) @ (index):12

The output shows the call stack at the time console.trace was called. It includes information about the functions in the stack, such as the function names and their respective locations in the code. In this example, the call stack is displayed in reverse order, with the most recent function call at the top.

3.7 console.dir

The console.dir() method allows you to display an interactive listing of the properties of a JavaScript object.

const obj = { name: "Chris", age: 25 };

// Display an interactive listing of the properties of the object
console.dir(obj);

The console.dir method is commonly used to log an interactive representation of an object to the console. If you run this code in a browser's developer console, the output might look something like this:

Object
  age: 25
  name: "Chris"
  __proto__: Object

This output provides a visual representation of the object's properties, including their names and values. It also shows the prototype of the object (__proto__). The console.dir method is particularly useful when dealing with complex objects or nested structures, as it allows you to explore the object's properties in a more interactive way than console.log.

3.8 console.clear

The console.clear() method clears the console of all previous log messages.

console.log("Message 1");

console.clear();

console.log("Message 2");

In the above example, console.clear() will clear the console before logging "Message 2".

4. Best Practices for Console Logging

While console logging can be a powerful debugging tool, it's important to use it judiciously and follow best practices:

• Avoid Excessive Logging: Too many log messages can clutter the console and make it difficult to find relevant information. Only log what is necessary for debugging.
• Use Descriptive Messages: When logging messages, use descriptive labels to make it clear what each message represents.
• Use Console Methods Wisely: Choose the appropriate console method (log, table, group, and so on) based on the type of data you are logging and how you want it to be displayed.
• Remove Debugging Code in Production: Remember to remove or disable console logging statements in your production code to avoid unnecessary overhead.

5. Conclusion

Console logging is a powerful tool for debugging JavaScript code. By leveraging advanced console logging tricks such as console.table, console.group, console.assert, and others, you can streamline your debugging process and gain deeper insights into your code's behavior.

In this comprehensive guide, we covered various console logging tricks, along with examples demonstrating how to use them effectively. By incorporating these techniques into your development workflow and following best practices, you can become a more efficient and effective developer.

Experiment with these console logging tricks in your own projects to see how they can help you debug and understand your code better. Happy debugging!

It doesn't matter if you're just starting out or have been coding for years. Knowing how to effectively use Developer Tools (DevTools for short) can significantly boost your development process. You can edit pages on the fly, quickly spot issues, and deeply understand your site's performance.

All major browsers have their own DevTools that let you examine the code of a webpage, evaluate its metrics, and run some tests alongside. This article will discuss Chrome's DevTools, as it's the industry standard.

Table of contents:

• What is Chrome DevTools?
• How to Open Chrome DevTools
• Keyboard shortcuts for Easy Navigation
• Key Chrome DevTools Features
• Practical DevTools Use Cases
• Conclusion

What is Chrome DevTools?

Chrome DevTools is a set of tools that are essential for diagnosing and solving web development challenges, directly within the Google Chrome browser.

It gives you direct access to a website's inner workings - to inspect HTML and CSS, debug JavaScript, analyze performance, and see the immediate impact of your code, all in realtime.

This direct access to a website's inner workings is crucial for diagnosing issues quickly and efficiently, ensuring your web applications are both performant and bug-free.

A grid of elements, console, performance and network panels screenshots

How to Open Chrome DevTools

To open DevTools in your Chrome browser, you can either:

1. Right-click on any webpage and select inspect from the list of options.
2. Use the shortcut (command + option + I on Mac or control + shift + I on Windows).
3. Click the three dot icon next to your profile picture on your Chrome browser, choose 'More Tools' and 'Developer Tools' from the second option box.

It usually opens in a split screen interface, either below your current webpage or beside it. Once open, its features line up as tabs at the top of the DevTools window. These tabs include: Elements, Console, Source, Network, Application, Security, Memory, Performance, Audits.

Keyboard Shortcuts for Easy Navigation

1. Use Cmd or Ctrl + Shift + C to open the Elements panel
2. Use Cmd or Ctrl + Shift + J to open the Console panel
3. Use Cmd or Ctrl + ] to move forward to the next panel
4. Use Cmd or Ctrl + [ to move back to the previous panel

Key Chrome DevTools Features

DevTools is packed with features essential for web developers to streamline various aspects of their workflow. Let's look at a few of them in some detail now.

Elements Panel

This panel is used for inspecting and modifying the HTML and CSS of a webpage in real-time, which is great for debugging layout issues or experimenting with new styles before applying them in your actual code. You also get to see how the DOM (Document Object Model) is structured.

Imagine fine-tuning your website's footer appearance (background color, font size) directly in your browser and seeing the results instantly.

With DevTools open, click on the Elements tab to access it.

A screenshot of Chrome DevTools' Elements panel

Console Panel

This panel serves as your interactive playground for JavaScript within the browser. Whether you're tracking down an elusive bug with a quick console.log() or experimenting with DOM elements, in the Console panel you can test snippets of JavaScript and view any logs or errors in the currently loaded webpage.

To use it, simply open DevTools and select the "Console" tab or use the shortcut (option + command + J on Mac or contrl + shift + J on Windows).

A screenshot of Chrome DevTools' Console panel

Network Panel

This panel gives you an overview of all network activity on your webpage – from tracking every resource that is loaded to how your site communicates with servers.

If you've wondered why your website takes forever to load or why some API requests seem to vanish into thin air, the Network panel is your go-to as it provides insights into the success or failure of API calls.

To access it, open DevTools and navigate to the "Network" tab.

A screenshot of Chrome DevTools' Network panel

Performance Panel

This panel is used for capturing and analyzing a website's performance metrics. It shows all the activities happening when interacting with a page.

When your web app starts to crawl under heavy usage, the Performance panel can pinpoint where the performance bottlenecks lie so that you can resolve these issues, ensuring your app runs smoothly.

With DevTools open, click on the "Performance" tab to use it.

A screenshot of Chrome DevTools' Performance panel

The above are only a handful of the panels available, but they're by far the most popular and must-knows. Using them properly will make your development processes more intuitive and rewarding.

Practical DevTools Use Cases

In the following interactive examples, I intentionally created the mini project in Codepen with issues to simulate real-world debugging scenarios using Chrome DevTools.

I figured it'd be a great way to highlight the practical uses of certain DevTools panels and features in identifying bugs and troubleshooting right in the browser.

Prerequisites

• Chrome browser (Click this link to download)
• A basic understanding of HTML, CSS, and JavaScript
• Codepen

See the Pen Modal Window by Ophy Boamah (@ophyboamah) on CodePen.

How to Debug HTML and CSS with the Elements Panel

Our mini project contains a modal that, upon clicking, should display a modal window with some important information. But there's a bug preventing this from happening.

This situation sets the stage for a practical demonstration of how you can use the Elements Panel to troubleshoot and resolve styling and structural issues.

<body>
  <button class="show-modal">Click me to learn a secret 🤫</button>

  <div class="modal hidden">
    <button class="close-modal">&times;</button>
    <h1>Hey Ophy here 👋🏾</h1>
    <p>
      I lead Women Who Code Frontend, a global remote community of 3,000+ women frontend devs and enthusiasts. Find us on beacons.ai/wwcodefrontend
    </p>
  </div>
  <div class="overlay hidden"></div>

  <script src="script.js"></script>
</body>

.hidden {
  display: none;
}

.modal {
  position: absolute;
  left: 50%;
  transform: translate(-50%);
  width: 70%;

  background-color: white;
  padding: 6rem;
  border-radius: 5px;
  box-shadow: 0 3rem 5rem rgba(0, 0, 0, 0.3);
  z-index: 10;
}

In our modal's HTML code above, we've added the class name 'modal hidden' which has a corresponding styling with the CSS property of display:none that is set to hide the modal when the page is loaded initially and only display it when the button is clicked.

✅ Step 1 - Initial inspection:

Attempt to trigger the modal by clicking on the 'Click me to learn a secret' button. Since we've set that up not to work, right-click on the area where the modal should appear and choose "Inspect" to open DevTools' Elements Panel.

✅ Step 2 - Diagnose visibility issues:

In the Elements Panel, locate the modal in the DOM to see that the modal is present but not visible. This confirms that the bug is caused within our CSS code display: hidden.

As soon as you click on the modal in the DOM, any corresponding CSS classes will be pulled up within Styles at the bottom section of the Elements panel. You can toggle some properties on and off or type others to see the effects in real-time.

Manually change the class name from modal hidden to modal block to trigger the right properties that'll cause the modal to show.

A screenshot of debugging the modal's HTML, CSS in Elements panel

✅ Step 3 - Center the modal:

Now the modal is visible, but it's displayed at the top – which is different from where we'd like it to be (that is, in the center of the page).

To change this, modify the transform property to translate(-50%, -50%) by adding the second -50% and ensure that top: 50%, and left: 50% are correctly set to center the modal on the screen.

✅ Step 4 - Enhance the appearance:

You can go further to refine the modal's appearance by tweaking its background-color, padding, or other stylistic properties directly within the Styles to achieve the desired look and feel.

A GIF fixing the modal in Chrome DevTools' Elements panel

Debug JavaScript with the Sources Panel

I added a bug in the JavaScript code of our modal mini project to prevent it from opening when the button is clicked.

In the real world, this would cause neither the open nor close commands to trigger any action, which would leave users unable to interact with the content and frustrated as a result. Let's troubleshoot and debug this issue in the Sources Panel.

In the code below, the openModal function is set to remove the indicated classes. However, this doesn't work because we deliberately misspelled hidden.

// Introducing a bug: Incorrectly spelling 'hidden' as 'hiddn'
const openModal = function () {
  modal.classList.remove("hiddn"); // Intentional bug
  overlay.classList.remove("hidden");

  // Fetch data from a real API and display in the modal
};

✅ Step 1 - Set up breakpoints:

Open Chrome DevTools and navigate to the Sources Panel. Here, find the JavaScript file that includes the modal functionality (in our example its pen.js).

The openModal function contains the logic for displaying the modal on the screen. This function will include a line where the modal element's class is manipulated to remove a "hidden" class.

Click on the number next to this code line in DevTools. A blue (or sometimes red, depending on the theme) icon appears next to the line number, indicating that a breakpoint has been set. This breakpoint will pause the execution of our JavaScript code as soon as it reaches this line.

A screenshot of setting breakpoints the modal's JS in Sources panel

Breakpoints pause code execution at critical points, allowing you to inspect the current state of variables and understand the flow of execution. This step is crucial for identifying where the code deviates from expected behaviour.

✅ Step 2 - Examine the code execution flow:

With our breakpoint in place, try to open the modal by clicking on its button. Execution of our JavaScript code now pauses at our breakpoint, which enables us to step through the code line by line.

This is an opportunity to observe variables, function calls, look for anomalies such as misnamed functions, incorrect logic, or uncaught exceptions that could explain why the modal isn't working.

In our case it's because we intentionally misspelled the class name hidden as hiddn. Fix that in the code to get the modal working again.

A GIF troubleshooting the modal bug in Chrome DevTools' Elements panel

Optimize Performance with the Network Panel

Here I've added a fetch function that makes an API call to a live endpoint (https://jsonplaceholder.typicode.com/posts/1). This is an excellent opportunity to explore the Network Panel's capabilities in diagnosing and understanding network-related problems.

From the code below, you can see that the openModal function doesn't only open the modal but also makes an API call to the jsonplaceholder endpoint to fetch some data.

const openModal = function () {
  fetch('https://jsonplaceholder.typicode.com/posts/1')
    .then(response => response.json())
    .then(json => document.getElementById('modal-content').innerText = json.title)
    .catch(error => console.error('Error loading the content:', error));
};

✅ Step 1 - Initiate the API call:

On the modal project UI, click on the 'Click me to learn a secret' button. Though the modal does not visibly activate, because of the fetch logic within the openModal function, an API call will be made.

✅ Step 2 - Network Panel Inspection:

Ideally, your Network Panel should be open before clicking the button, but you can also reverse the steps. Detailed insights on your API request such as the request's method, status code, response and the time it took to complete, will be available under headers, preview, response, initiator and timing tabs respectively.

A screenshot overview of API request in Network panel

✅ Step 3 - Simulating Network Conditions:

Use the Network Panel's throttling feature to mimic various network speeds like offline or slow 3G to see how the API request behaves under constrained conditions.

From this you can compare how different network speeds can affect application performance. This will teach you the importance of optimizing data loading strategies to enhance user experience, especially on slower connections.

A GIF observing API requests and responses in Chrome DevTools' Network panel

Conclusion

Bringing Chrome DevTools into your web development routine is not just about fixing bugs. It's about streamlining your workflow, making your sites more accessible, and boosting their performance.

Through our modal window mini-project, we've seen firsthand how DevTools can address a wide array of development challenges, but that’s merely scratching the surface of what it can do.

As you continue to explore its capabilities and familiarize yourself with its features, you'll find it's an invaluable companion on your web development journey – designed to make your development process not just faster, but also more rewarding.

• The Official Chrome DevTools documentation
• How to use the Chrome DevTools to troubleshoot websites

Also, writing quality and performant code helps your program or website work as expected – which should be every developer's goal.

SonarLint is a tool that helps you make sure your code is top-notch. It's like having a friendly guide who checks your code to see if it's well-written and doesn't have mistakes.

What is SonarLint?

SonarLint is an open-source code analysis tool that helps you find and resolve security and code quality problems in your source code as you're writing it. This plugin works with several integrated development environments (IDEs), including well-known ones like IntelliJ IDEA, Eclipse, and Visual Studio.

SonarLint's main purpose is to give you immediate feedback on possible problems with your code, including security flaws, bugs, and other recommended practices for programming. SonarLint analyzes code in the background while you create or change it in your IDE, giving you instant feedback and frequently exposing problems right in the code editor.

SonarLint is a component of the larger SonarQube ecosystem.

In this article, I'll teach you how to use SonarLint to help you write quality code.

Why is SonarLint Useful?

Let's imagine that building a website is like constructing a house. You want your house to be safe and well-designed, right? Well, SonarLint is like having a thorough inspector who checks your work as you build, making sure everything is just right.

Here's why SonarLint is important in web development:

1. Catch Mistakes Early (Code Quality): Assuming you were building a staircase, and accidentally put a step in the wrong place, SonarLint is like a smart friend who tells you immediately, "Hey, you might have made a mistake here!" It helps catch small errors in your code before they become big problems.

2. Follow the Blueprint (Coding Standards): When building a house, you follow a blueprint to make sure everything fits together. In coding, there are also rules (like a blueprint) on how to write good code. SonarLint helps you stick to these rules, making your code easy to read and work with.

3. Keep It Secure (Security): Just like you'd want your house to have good locks on the doors, you'd want your website to be secure. SonarLint checks your code for potential security issues, ensuring there are no "unlocked doors" that could let bad things happen.

4. Work Together Well (Collaboration): Imagine that each builder in your team used a different kind of tool. It would be chaos! SonarLint helps your team work together smoothly by making sure everyone follows the same coding standards. This way, everyone can understand and contribute to the project easily.

5. Save Time and Effort (Efficiency): Fixing mistakes after the whole house is built would take a lot of time and effort. SonarLint helps you fix issues as you go, saving you from returning and redoing things. It's like having a helpful friend who stops you from making mistakes in the first place.

6. Learn and Improve (Education): SonarLint does not only point out mistakes but also explains why they might be a problem. It's like having a coding teacher who helps you understand how to write better code. This way, you learn and become a better developer over time.

So, in the world of web development, SonarLint is your coding buddy, and it makes sure your JavaScript "house" is strong, secure, and well-organized from the ground up. It's a valuable tool in your workflow and helps you create high-quality websites that everyone can enjoy.

But you still may be wondering why you need this tool. You have a debugger already installed in your IDE and it can already track the errors in your environment.

Well, integrating SonarLint complements your debugger by focusing on code quality and security during development.

While a debugger helps to find and fix runtime issues, SonarLint analyzes code in real time, identifies bugs and potential vulnerabilities, and enforces coding standards.

You can also customize and configure coding rules based on your project's specific requirements and coding standards.

This proactive approach enhances overall code quality and ensures cleaner, more maintainable code before it reaches the debugging stage. This leads to fewer errors and smoother development workflows.

Before we get into the details of how to set up and use SonarLint, let's look at what makes code high-quality.

Code Quality Metrics

Be the best cookbook author! When writing code there are specific guidelines you must follow.

Just like when you're cooking up a new recipe or want to follow a traditional one, you should make sure anyone who reads it can follow along, and that the recipe you wrote down results in a good dish.

In the same sense, when writing code, it's always important to make your code readable so that other developers can understand it easily and so your code works as it's supposed to. Code quality metrics are like measuring how well you followed the recipe.

Here's a breakdown:

Readability (Clarity): This is similar to making sure your recipe instructions are clear. The code should be easy for others (or future you) to understand.

Maintainability (Ease of Changes): If you had to change ingredients in your recipe (code), it should be easy to switch things without chaos.

Performance (Speed): As you'd want your meal ready quickly, efficient code is expected to run fast. Code quality metrics check how fast your code is executed.

Reliability (Consistency): A good recipe always tastes the same. Similarly, reliable code consistently produces the correct results.

Security (Safety): Just like checking if ingredients are safe to eat, code quality metrics look for potential dangers in your code that could be exploited.

These should be your goals when writing quality code. And SonarLint can help you accomplish them.

How to Set Up SonarLint and Integrate with Your IDE

An IDE (Integrated Development Environment) is a software application that helps developers write and debug code more effectively. IDEs include a code editor and compiler or interpreter.

In this article, you'll see how to install SonarLint using VS Code extensions.

How to Install SonarLint with VS Code

First, install VS Code or open the application if you've already installed it.

Next, head over to the Extensions tab on VS Code and download the SonarLint extension.

To use the SonarLint extension for JavaScript, TypeScript, or CSS, you should have a minimum version of 14.17.0 of Node.js installed on your system (especially if you want to use Connected Mode with Sonar Cloud).

Install SonarLint in VS Code

Now that you've installed SonarLint, running an analysis on your code should be easy and it should start immediately after you open a new file.

This means SonarLint will start working and catching errors in your code as you write them on your IDE. Now let's look at an example in the next section.

How to Use SonarLint in Your IDE

Now let's look at how you can get the best out of SonarLint on your IDE. SonarLint is also a wonderful teacher, helping you better understand how to write clean code and giving you more information about why you have an error.

So instead of scouring the web to figure out what's wrong with your code, SonarLint explains why it has given you an error.

Here's an example of how to use it.

To be able to see the interface where we'll be working, open your terminal on VS Code – you can use Ctrl + backtick (`) to do this. I'm currently working on a project in React.js, and I didn't notice that I have duplicate border property names in my CSS class. Luckily, SonarLint caught this issue.

A CSS error caught by SonarLint

If you click on the light bulb, you'll see an option to fix the code by deactivating the CSS rule or to be blunt removing the extra border which I have in my CSS class in this instance. There's also another option for opening a description rule so you can understand why you're getting that error.

So SonarLint gives you two options:

1. It offers an option that gives you the ability and resources to understand why you have that error with the "Open description of rule".

2. It offers a solution to the error of the code which it has found.

Options offered by SonarLint to help fix and understand this problem

If you click on the open description rule, SonarLint opens another tab in VS Code to help you understand why it has thrown that error and how you can write cleaner/better code.

Tab opened by SonarLint in VSCode to help understand the error

As you can see, SonarLint is an excellent teacher and your best buddy as you continue to build and work on your IDE.

Another great thing about SonarLint is that it works with multiple programming languages. So whatever programming language you're using, chances are that SonarLint can handle it.

Conclusion

SonarLint is like having a coding buddy that helps you become a better programmer. As you write code, it's like having a teacher right there with you, pointing out ways to improve.

Imagine having a super-smart friend who does not just spot mistakes but also explains why they're wrong and shows you how to fix them.

Before your code gets to the testing stage, SonarLint checks for mistakes and makes sure your program runs smoothly. It's like having a superpower to catch issues early, saving you time and effort.

But that's not all! SonarLint is also like a security guard for your code. It watches out for any potential weak points that could let bad things happen. By learning from SonarLint, you can write better code and become more aware of keeping your code safe and secure.

So in this article we'll talk about what the term "clean code" means, why it's important, how can we assess whether a codebase is clean or not. You'll also learn some best practices and conventions you can follow to make your code cleaner.

Let's go!

Table of Contents

• What does it mean to write "clean code" and why should I care?

• How can I assess whether a codebase is clean or not?

• Tips and conventions to write cleaner code

  • Effectiveness, efficiency and simplicity

  • Format and syntax

  • Naming

  • Conciseness versus clarity

  • Re-usability

  • Clear flow of execution

  • Single responsibility principle

  • Having a "single source of truth"

  • Only expose and consume information you need

  • Modularization

  • Folder structures

  • Documentation

• Wrapping up

What Does it Mean to Write "Clean Code" and Why Should I Care?

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.

How Can I Assess Whether a Codebase is Clean or Not?

You can assess clean code in a variety of ways. Good documentation, consistent formatting, and a well-organized codebase are all indicators of clean code.

Code reviews can also help to identify potential issues and ensure that code follows best practices and conventions.

Testing is also an important aspect of clean code. It helps to ensure that code is functioning as expected and can catch errors early.

There are several tools, practices, and conventions you can implement to ensure a clean codebase. By implementing these tools and practices, developers can create a codebase that is easy to read, understand, and maintain.

It's also important to remember that there's an inevitable amount of subjectivity related to this topic, and there are a number of different opinions and tips out there. What might look clean and awesome for one person or one project might not be so for another person or another project.

But still there are a few general conventions we can follow to achieve cleaner code, so let's jump into that now.

Tips and Conventions to Write Cleaner Code

Effectiveness, Efficiency and Simplicity

Whenever I need to think about how to implement a new feature into an already existing codebase, or how to tackle the solution of a specific problem, I always prioritize this three simple things.

Effectiveness

First, our code should be effective, meaning it should solve the problem it's supposed to solve. Of course this is the most basic expectation we could have for our code, but if our implementation doesn't actually work, it's worthless to think about any other thing.

Efficiency

Second, once we know our code solves the problem, we should check if it does so efficiently. Does the program run using a reasonable amount of resources in terms of time and space? Can it run faster and with less space?

Algorithmic complexity is something you should be aware of in order to evaluate this. If you're not familiar with it, you can check this article I wrote.

To expand upon efficiency, here are two examples of a function that calculates the sum of all numbers in an array.

// Inefficient Example
function sumArrayInefficient(array) {
  let sum = 0;
  for (let i = 0; i < array.length; i++) {
    sum += array[i];
  }
  return sum;
}

This implementation of the sumArrayInefficient function iterates over the array using a for loop and adds each element to the sum variable. This is a valid solution, but it is not very efficient because it requires iterating over the entire array, regardless of its length.

// Efficient example
function sumArrayEfficient(array) {
  return array.reduce((a, b) => a + b, 0);
}

This implementation of the sumArrayEfficient function uses the reduce method to sum the elements of the array. The reduce method applies a function to each element of the array and accumulates the result. In this case, the function simply adds each element to the accumulator, which starts at 0.

This is a more efficient solution because it only requires a single iteration over the array and performs the summing operation on each element as it goes.

Simplicity

And last comes simplicity. This is the toughest one to evaluate because its 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 clearly 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 quick can you identify in which part of the codebase are certain features of the program? Can you delete/add new features without the need of modifying many other parts of the code?

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

7. Is code reused when possible?

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

By following and prioritizing these three concepts of effectiveness, efficiency, and simplicity, we can always have a guideline to follow when thinking about how to implement a solution. Now let's expand upon some of the guidelines that can help us simplify our code.

Format and Syntax

Using consistent formatting and syntax throughout a codebase is an important aspect of writing clean code. This is because consistent formatting and syntax make the code more readable and easier to understand.

When code is consistent, developers can easily identify patterns and understand how the code works, which makes it easier to debug, maintain, and update the codebase over time. Consistency also helps to reduce errors, as it ensures that all developers are following the same standards and conventions.

Some of the things we should think about regarding format and syntax are:

• Indentation and spacing

// bad indentation and spacing
const myFunc=(number1,number2)=>{
const result=number1+number2;
return result;
}

// good indentation and spacing
const myFunc = (number1, number2) => {
    const result = number1 + number2
    return result
}

Here we have an example of a same function, one done with no indentation and spacing, and the other properly spaced and indented. We can see that the second one is clearly easier to read.

• Consistent syntax

// Arrow function, no colons, no return
const multiplyByTwo = number => number * 2

// Function, colons, return
function multiplyByThree(number) {
    return number * 3;
}

Again, here we have very similar functions implemented with different syntax. The first one is an arrow function, with no colons and no return, while the other is a common function that uses colons and a return.

Both work and are just fine, but we should aim to always use the same syntax for similar operations, as it becomes more even and readable along the codebase.

Linterns and code formatters are great tools we can use in our projects to automatize the syntax and formatting conventions in our codebase. If you're not familiar with this tools, check out this other article of mine.

• Consistent case conventions

// camelCase
const myName = 'John'
// PascalCase
const MyName = 'John'
// snake_case
const my_name = 'John'

Same goes for the case convention we choose to follow. All of these work, but we should aim to consistently use the same one all through our project.

Naming

Naming variables and functions clearly and descriptively is an important aspect of writing clean code. It helps to improve the readability and maintainability of the codebase. When names are well-chosen, other developers can quickly understand what the variable or function is doing, and how it is related to the rest of the code.

Here are two examples in JavaScript that demonstrate the importance of clear and descriptive naming:

// Example 1: Poor Naming
function ab(a, b) {
  let x = 10;
  let y = a + b + x;
  console.log(y);
}

ab(5, 3);

In this example, we have a function that takes two parameters, adds them to a hardcoded value of 10, and logs the result to the console. The function name and variable names are poorly chosen and don't give any indication of what the function does or what the variables represent.

// Example 1: Good Naming
function calculateTotalWithTax(basePrice, taxRate) {
  const BASE_TAX = 10;
  const totalWithTax = basePrice + (basePrice * (taxRate / 100)) + BASE_TAX;
  console.log(totalWithTax);
}

calculateTotalWithTax(50, 20);

In this example, we have a function that calculates the total price of a product including tax. The function name and variable names are well-chosen and give a clear indication of what the function does and what the variables represent.

This makes the code easier to read and understand, especially for other developers who may be working with the codebase in the future.

Conciseness vs Clarity

When it comes to writing clean code, it's important to strike a balance between conciseness and clarity. While it's important to keep code concise to improve its readability and maintainability, it's equally important to ensure that the code is clear and easy to understand. Writing overly concise code can lead to confusion and errors, and can make the code difficult to work with for other developers.

Here are two examples that demonstrate the importance of conciseness and clarity:

// Example 1: Concise function
const countVowels = s => (s.match(/[aeiou]/gi) || []).length;
console.log(countVowels("hello world"));

This example uses a concise arrow function and regex to count the number of vowels in a given string. While the code is very short and easy to write, it may not be immediately clear to other developers how the regex pattern works, especially if they are not familiar with regex syntax.

// Example 2: More verbose and clearer function
function countVowels(s) {
  const vowelRegex = /[aeiou]/gi;
  const matches = s.match(vowelRegex) || [];
  return matches.length;
}

console.log(countVowels("hello world"));

This example uses a traditional function and regex to count the number of vowels in a given string, but does so in a way that is clear and easy to understand. The function name and variable names are descriptive, and the regex pattern is stored in a variable with a clear name. This makes it easy to see what the function is doing and how it works.

It's important to strike a balance between conciseness and clarity when writing code. While concise code can improve readability and maintainability, it's important to ensure that the code is still clear and easy to understand for other developers who may be working with the codebase in the future.

By using descriptive function and variable names, and making use of clear and readable code formatting and comments, it's possible to write clean and concise code that is easy to understand and work with.

Reusability

Code reusability is a fundamental concept in software engineering that refers to the ability of code to be used multiple times without modification.

The importance of code reusability lies in the fact that it can greatly improve the efficiency and productivity of software development by reducing the amount of code that needs to be written and tested.

By reusing existing code, developers can save time and effort, improve code quality and consistency, and minimize the risk of introducing bugs and errors. Reusable code also allows for more modular and scalable software architectures, making it easier to maintain and update codebases over time.

// Example 1: No re-usability
function calculateCircleArea(radius) {
  const PI = 3.14;
  return PI * radius * radius;
}

function calculateRectangleArea(length, width) {
  return length * width;
}

function calculateTriangleArea(base, height) {
  return (base * height) / 2;
}

const circleArea = calculateCircleArea(5);
const rectangleArea = calculateRectangleArea(4, 6);
const triangleArea = calculateTriangleArea(3, 7);

console.log(circleArea, rectangleArea, triangleArea);

This example defines three functions that calculate the area of a circle, rectangle, and triangle, respectively. Each function performs a specific task, but none of them are reusable for other similar tasks.

Additionally, the use of a hard-coded PI value can lead to errors if the value needs to be changed in the future. The code is inefficient since it repeats the same logic multiple times.

// Example 2: Implementing re-usability
function calculateArea(shape, ...args) {
  if (shape === 'circle') {
    const [radius] = args;
    const PI = 3.14;
    return PI * radius * radius;
  } else if (shape === 'rectangle') {
    const [length, width] = args;
    return length * width;
  } else if (shape === 'triangle') {
    const [base, height] = args;
    return (base * height) / 2;
  } else {
    throw new Error(`Shape "${shape}" not supported.`);
  }
}

const circleArea = calculateArea('circle', 5);
const rectangleArea = calculateArea('rectangle', 4, 6);
const triangleArea = calculateArea('triangle', 3, 7);

console.log(circleArea, rectangleArea, triangleArea);

This example defines a single function calculateArea that takes a shape argument and a variable number of arguments. Based on the shape argument, the function performs the appropriate calculation and returns the result.

This approach is much more efficient since it eliminates the need to repeat code for similar tasks. It is also more flexible and extensible, as additional shapes can easily be added in the future.

Clear Flow of Execution

Having a clear flow of execution is essential for writing clean code because it makes the code easier to read, understand, and maintain. Code that follows a clear and logical structure is less prone to errors, easier to modify and extend, and more efficient in terms of time and resources.

On the other hand, spaghetti code is a term used to describe code that is convoluted and difficult to follow, often characterized by long, tangled, and unorganized code blocks. Spaghetti code can be a result of poor design decisions, excessive coupling, or lack of proper documentation and commenting.

Here are two examples of JavaScript code that perform the same task, one with a clear flow of execution, and the other with spaghetti code:

// Example 1: Clear flow of execution
function calculateDiscount(price, discountPercentage) {
  const discountAmount = price * (discountPercentage / 100);
  const discountedPrice = price - discountAmount;
  return discountedPrice;
}

const originalPrice = 100;
const discountPercentage = 20;
const finalPrice = calculateDiscount(originalPrice, discountPercentage);

console.log(finalPrice);

// Example 2: Spaghetti code
const originalPrice = 100;
const discountPercentage = 20;

let discountedPrice;
let discountAmount;
if (originalPrice && discountPercentage) {
  discountAmount = originalPrice * (discountPercentage / 100);
  discountedPrice = originalPrice - discountAmount;
}

if (discountedPrice) {
  console.log(discountedPrice);
}

As we can see, example 1 follows a clear and logical structure, with a function that takes in the necessary parameters and returns the calculated result. On the other hand, example 2 is much more convoluted, with variables declared outside of any function and multiple if statements used to check if the code block has executed successfully.

Single Responsibility Principle

The Single Responsibility Principle (SRP) is a principle in software development that states that each class or module should have only one reason to change, or in other words, each entity in our codebase should have a single responsibility.

This principle helps to create code that is easy to understand, maintain, and extend.

By applying SRP, we can create code that is easier to test, reuse, and refactor, since each module only handles a single responsibility. This makes it less likely to have side effects or dependencies that can make the code harder to work with.

// Example 1: Withouth SRP
function processOrder(order) {
  // validate order
  if (order.items.length === 0) {
    console.log("Error: Order has no items");
    return;
  }

  // calculate total
  let total = 0;
  order.items.forEach(item => {
    total += item.price * item.quantity;
  });

  // apply discounts
  if (order.customer === "vip") {
    total *= 0.9;
  }

  // save order
  const db = new Database();
  db.connect();
  db.saveOrder(order, total);
}

In this example, the processOrder function handles several responsibilities: it validates the order, calculates the total, applies discounts, and saves the order to a database. This makes the function long and hard to understand, and any changes to one responsibility may affect the others, making it harder to maintain.

// Example 2: With SRP
class OrderProcessor {
  constructor(order) {
    this.order = order;
  }

  validate() {
    if (this.order.items.length === 0) {
      console.log("Error: Order has no items");
      return false;
    }
    return true;
  }

  calculateTotal() {
    let total = 0;
    this.order.items.forEach(item => {
      total += item.price * item.quantity;
    });
    return total;
  }

  applyDiscounts(total) {
    if (this.order.customer === "vip") {
      total *= 0.9;
    }
    return total;
  }
}

class OrderSaver {
  constructor(order, total) {
    this.order = order;
    this.total = total;
  }

  save() {
    const db = new Database();
    db.connect();
    db.saveOrder(this.order, this.total);
  }
}

const order = new Order();
const processor = new OrderProcessor(order);

if (processor.validate()) {
  const total = processor.calculateTotal();
  const totalWithDiscounts = processor.applyDiscounts(total);
  const saver = new OrderSaver(order, totalWithDiscounts);
  saver.save();
}

In this example, the processOrder function has been split into two classes that follow the SRP: OrderProcessor and OrderSaver.

The OrderProcessor class handles the responsibilities of validating the order, calculating the total, and applying discounts, while the OrderSaver class handles the responsibility of saving the order to the database.

This makes the code easier to understand, test, and maintain, since each class has a clear responsibility and can be modified or replaced without affecting the others.

Having a "Single Source of Truth"

Having a "single source of truth" means that there is only one place where a particular piece of data or configuration is stored in the codebase, and any other references to it in the code refer back to that one source. This is important because it ensures that the data is consistent and avoids duplication and inconsistency.

Here's an example to illustrate the concept. Let's say we have an application that needs to display the current weather conditions in a city. We could implement this feature in two different ways:

// Option 1: No "single source of truth"

// file 1: weatherAPI.js
const apiKey = '12345abcde';

function getCurrentWeather(city) {
  return fetch(`https://api.weather.com/conditions/v1/${city}?apiKey=${apiKey}`)
    .then(response => response.json());
}

// file 2: weatherComponent.js
const apiKey = '12345abcde';

function displayCurrentWeather(city) {
  getCurrentWeather(city)
    .then(weatherData => {
      // display weatherData on the UI
    });
}

In this option, the API key is duplicated in two different files, making it harder to maintain and update. If we ever need to change the API key, we have to remember to update it in both places.

// Option 2: "Single source of truth"

// file 1: weatherAPI.js
const apiKey = '12345abcde';

function getCurrentWeather(city) {
  return fetch(`https://api.weather.com/conditions/v1/${city}?apiKey=${apiKey}`)
    .then(response => response.json());
}

export { getCurrentWeather, apiKey };


// file 2: weatherComponent.js
import { getCurrentWeather } from './weatherAPI';

function displayCurrentWeather(city) {
  getCurrentWeather(city)
    .then(weatherData => {
      // display weatherData on the UI
    });
}

In this option, the API key is stored in one place (in the weatherAPI.js file) and exported for other modules to use. This ensures that there is only one source of truth for the API key and avoids duplication and inconsistency.

If we ever need to update the API key, we can do it in one place and all other modules that use it will automatically get the updated value.

Only Expose and Consume 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'

Modularization

Modularization is an essential concept in writing clean code. It refers to the practice of breaking down large, complex code into smaller, more manageable modules or functions. This makes the code easier to understand, test, and maintain.

Using modularization provides several benefits such as:

1. Re-usability: Modules can be reused in different parts of the application or in other applications, saving time and effort in development.

2. Encapsulation: Modules allow you to hide the internal details of a function or object, exposing only the essential interface to the outside world. This helps to reduce coupling between different parts of the code and improve overall code quality.

3. Scalability: By breaking down large code into smaller, modular pieces, you can easily add or remove functionality without affecting the entire codebase.

Here is an example in JavaScript of a piece of code that performs a simple task, one not using modularization and the other implementing modularization.

// Without modularization
function calculatePrice(quantity, price, tax) {
  let subtotal = quantity * price;
  let total = subtotal + (subtotal * tax);
  return total;
}

// Without modularization
let quantity = parseInt(prompt("Enter quantity: "));
let price = parseFloat(prompt("Enter price: "));
let tax = parseFloat(prompt("Enter tax rate: "));

let total = calculatePrice(quantity, price, tax);
console.log("Total: $" + total.toFixed(2));

In the above example, the calculatePrice function is used to calculate the total price of an item given its quantity, price, and tax rate. However, this function is not modularized and is tightly coupled with the user input and output logic. This can make it difficult to test and maintain.

Now, let's see an example of the same code using modularization:

// With modularization
function calculateSubtotal(quantity, price) {
  return quantity * price;
}

function calculateTotal(subtotal, tax) {
  return subtotal + (subtotal * tax);
}

// With modularization
let quantity = parseInt(prompt("Enter quantity: "));
let price = parseFloat(prompt("Enter price: "));
let tax = parseFloat(prompt("Enter tax rate: "));

let subtotal = calculateSubtotal(quantity, price);
let total = calculateTotal(subtotal, tax);
console.log("Total: $" + total.toFixed(2));

In the above example, the calculatePrice function has been broken down into two smaller functions: calculateSubtotal and calculateTotal. These functions are now modularized and are responsible for calculating the subtotal and total, respectively. This makes the code easier to understand, test, and maintain, and also makes it more reusable in other parts of the application.

Modularization can also refer to the practice of dividing single files of code into many smaller files that are later on compiled back on to a single (or fewer files). This practice has the same benefits we just talked about.

If you'd like to know how to implement this in JavaScript using modules, check out this other article of mine.

Folder Structures

Choosing a good folder structure is an essential part of writing clean code. A well-organized project structure helps developers find and modify code easily, reduces code complexity, and improves project scalability and maintainability.

On the other hand, a poor folder structure can make it challenging to understand the project's architecture, navigate the codebase, and lead to confusion and errors.

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.

But 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 own folder, which contains all the files related to that feature.

This approach makes it easy to find and modify code, as all the files related to a feature are located in the same folder. It also reduces code duplication and complexity, as features are separated, and their related files are organized together.

Overall, a good folder structure should be organized around features, not file types, and should make it easy to find and modify code. A clear and logical structure can make a project easier to maintain, understand and scale, while a confusing and inconsistent structure can lead to errors and confusion.

If you're interested in learning more about this, in this article I wrote about software architecture I expanded upon the topic of folder structures and well-known patterns you can follow.

Documentation

Documentation is an essential part of writing clean code. Proper documentation not only 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.

Documenting is specially important in cases in which simple and easy to understand solutions can't be implemented, cases when the business logic is quite complex, and cases in which people who are not familiar with the codebase have to interact with it.

One way to document code is by using comments. Comments can provide context and explain what the code is doing. But it's important to use comments wisely, only commenting where necessary and avoiding redundant or unnecessary ones.

Another way to document code is by using inline documentation. Inline documentation is embedded in the code itself and can be used to explain what a specific function or piece of code does. Inline documentation is often used in combination with tools like JSDoc, which provides a standard for documenting code in JavaScript.

Tools like Typescript can also provide automatic documentation for our codebase, which is hugely helpful.

If you'd like to know more about Typescript, I wrote a beginner friendly guide a while ago.

And Lastly, tools like Swagger and Postman can be used to document APIs, providing a way to easily understand how to interact with them

If you're interested in knowing how to fully implement, test, consume and document APIs, I recently wrote two guides for REST APIs and GraphQL APIs.

Wrapping Up

Well everyone, as always, I hope you enjoyed the article and learned something new.

If you want, you can also follow me on LinkedIn or Twitter. See you in the next one!

We're going to talk about what these tools are, how they work, why are they useful, and finally see how we can implement them in a basic React project.

Let's go!

Table of Contents

• About linting tools

  • What are Linting Tools?

  • Why are Linting Tools Useful?

  • Main Linting Tools in the Market

• About code formatters

  • What are Code Formatters?

  • Why are Code Formatters Useful?

  • Main Code Formatters Available

• How to Implement ESLint and Prettier

  • How to Install ESLint

  • How to Install Prettier

• Wrapping up

About Linting Tools

In the world of web development, linting tools have become an essential part of the developer's toolkit.

Linting tools are used to analyze source code for potential errors or stylistic issues, making it easier to maintain code quality and consistency across a project.

What are Linting Tools?

Linting tools are automated tools that analyze source code to detect potential errors, security vulnerabilities, or coding style issues.

They are designed to help developers catch mistakes before they become a problem, and to promote best practices in coding.

The term "lint" comes from the name of the first lint tool, which was developed in the early 1970s by a team of Bell Labs researchers led by Stephen C. Johnson.

The original lint tool was designed to analyze C source code for potential errors and stylistic issues.

Since then, linting tools have evolved to work with a variety of programming languages, including JavaScript, Python, and Ruby.

Why are Linting Tools Useful?

Linting tools are useful for a number of reasons. Firstly, they help you catch errors early in the development process, when they are easier and cheaper to fix.

Secondly, they can help promote coding standards and best practices within a development team, ensuring that code is consistent and maintainable.

Finally, they can help you identify potential security vulnerabilities in your code, reducing the risk of a breach.

Main Linting Tools in the Market

There are several linting tools available in the market today. Here are some of the most popular ones:

1. ESLint: ESLint is a widely used and highly configurable linter for JavaScript and TypeScript. It can be extended using plugins and supports various rule sets, making it a flexible tool for enforcing coding standards and preventing errors.

2. JSHint: JSHint is a popular linter that has been around since 2010. It offers a simple configuration and a wide range of built-in rules to help developers avoid common pitfalls and improve code quality.

3. JSLint: JSLint was one of the first linters to be developed for JavaScript, and it still sees some use today. It is known for its strictness and for enforcing a particular style of code, which can be helpful for maintaining consistency across a team.

4. StandardJS: StandardJS is a popular linter that aims to provide a "batteries included" approach to JavaScript linting. It has a minimal configuration and includes a set of opinionated rules designed to promote clean, readable code.

And we should also talk about Typescript. When using TypeScript, the TypeScript compiler itself acts as a linter. It checks the syntax of TypeScript code and provides warnings and errors when there are issues. This built-in linter can catch common mistakes and issues such as misspelled variable names, invalid method calls, and syntax errors.

The TypeScript compiler can be run using the tsc command in a terminal. When the --noEmit flag is used, the TypeScript compiler will only perform a syntax check without compiling the code to JavaScript. This allows the compiler to act as a linter and provide feedback on code quality without actually generating any output.

You can also configure the TypeScript compiler using a tsconfig.json file to specify various options, including the strictness of the checking. This can help catch even more potential issues and ensure that the code follows best practice

If you're not familiar with TypeScript, I recommend you this article I wrote a while ago.

About Code Formatters

In modern web development, code formatters have become an essential tool for developers. These tools automate the process of code formatting, making it easier to write and read code.

What are Code Formatters?

Code formatters are automated tools that help you format source code automatically. The main purpose of code formatters is to standardize the formatting of code across a project or team, making it easier to read and understand code.

With code formatters, developers no longer need to spend time formatting code manually, which can save a lot of time and effort.

Code formatting tools have been around for decades. One of the earliest tools was the "indent" program, which was used to format C code in the early 1970s. But these early tools were limited and didn't have the same level of functionality as modern code formatters.

In the early 2000s, tools like "astyle" and "uncrustify" were developed, which introduced more advanced formatting capabilities.

Why are Code Formatters Useful?

Code formatters are useful for a variety of reasons. First and foremost, they help to standardize code formatting, which makes it easier to read and understand code. This is particularly important when working on large projects with multiple developers, where everyone needs to be able to read and understand each other's code.

Code formatters also help to ensure that code is consistent across a project or team, which can help to prevent errors and improve code quality. They also make it easier to maintain code over time, as the code is formatted consistently and is easier to read and understand.

Main Code Formatters Available

There are several code formatting tools available in the market today. Here are some of the most popular ones:

1. Prettier: Prettier is a popular code formatter for JavaScript, TypeScript, and CSS. It's highly configurable and can be used in a variety of different environments, including editors, build tools, and code quality checkers.

2. ESLint: While primarily known as a linting tool, ESLint can also be used as a code formatter. It has a --fix flag that can automatically format your code based on rules you define.

3. Beautify: Beautify is a code formatter for JavaScript, HTML, and CSS that can be used in a variety of editors and IDEs. It allows you to customize your formatting options and has support for a wide range of languages.

How to Implement ESLint and Prettier

Cool, so now let's see a linter and code formatter in action! We're going to implement the two most popular tools (ESLint and Prettier) in a simple React project to get an idea of how these things work.

First let's create our project by running this in our command line: npm create vite@latest linternsAndFormatters --template react

Then cd into your project and run npm install so our dependencies get installed.

Now that we have our project up and running, we'll start by installing ESLint.

How to Install ESLint

To install ESLint, we can just run npm init @eslint/config in our console. This will fire a series of prompts asking how we want to use ESLint in our project and building the corresponding config. Your console might end up looking something like this:

Installing ESLint

After all this, we'll see a new file called .eslintrc.cjs in the root of our project. Here's where ESLint's config lives and where we can customize the linter to our preferences. The initial config given the options I selected is the following:

module.exports = {
    "env": {
        "browser": true,
        "es2021": true
    },
    "extends": [
        "eslint:recommended",
        "plugin:react/recommended"
    ],
    "overrides": [
    ],
    "parserOptions": {
        "ecmaVersion": "latest",
        "sourceType": "module"
    },
    "plugins": [
        "react"
    ],
    "rules": {
    }
}

To see our linter in action, let's add the following script in our package.json file:

"lint": "eslint --fix . --ext .js,.jsx"

This script executes the eslint command with the --fix option to automatically fix linting errors and warnings. The command is executed on all files with the .js or .jsx extension located in the root directory of the project, as specified by the . argument.

Now let's modify our app.jsx file to have the following code:

import React from 'react'
import './App.css'

function App() {

  const emptyVariable = ''

  return (
    <div className="App">
      <h1>Vite + React</h1>
    </div>
  )
}

export default App

Then run npm run lint and voilà! Your linter is screaming with red highlighted text that you have an unused variable in your code! =D

How to Install Prettier

Cool, now let's hop on to our code formatter.

We're going to install it by running npm install --save-dev --save-exact prettier.

Then we're going to create and empty config file by running echo {}> .prettierrc.json.

Since we're here, add the following options to your newly created config file:

{
  "singleQuote": true,
  "jsxSingleQuote": true,
  "semi": false
}

What this does is assure single quotes are used whenever possible and semicolons are nowhere to be found (because, god, who likes semicolons...).

As we did with our linter, let's add the following script in our package.json file:

    "format": "prettier --write ."

The script runs the Prettier code formatter on all the files in the project directory and its sub-directories. When run with the --write option, it modifies the files in place, changing them to conform to Prettier's rules for indentation, line length, and other formatting options. The . argument specifies that all files in the project directory and its sub directories should be formatted.

Lastly, let's "uglify" the first line of our app.jsx file like this:

import React from "react";

Run npm run format and you should see it corrected right in front of you:

import React from 'react'

You can breath easy now, those ugly semicolons won't come back to haunt you. ;)

As we've seen, the set up of these two tools isn't that complex, and they truly help to make our everyday jobs easier. ESLint will help us catch bugs and unnecessary/redundant code, and Prettier will help us standardize code format all across our codebase.

Another tip is that if you have a CI/CD pipeline in place, it's a good idea to implement the linting and formatting scripts as part of your workflow. This will help you ensure that every deployment is both automatically linted and formatted.

If you're not familiar with CI/CD or setting up a pipeline, I recently wrote an article about that. ;)

Wrapping up

Linters and code formatters are powerful tools that can greatly benefit web developers.

Linters help you catch potential bugs and issues before they become serious problems, and encourage you to write more maintainable and readable code.

Code formatters help you enforce a consistent code style and format, saving time and reducing the chances of human error.

By using these tools in your web development workflow, you can improve your productivity and the quality of your code.

As always, I hope you enjoyed the article and learned something new.

If you want, you can also follow me on LinkedIn or Twitter. See you in the next one!

This is why code formatters are so useful.

A code formatter is a tool that formats code according to certain standards. It makes it so you don't have to worry as much about code formatting. Instead, you can focus on writing good code. This save time and also reduces your stress.

In this guide, we will talk about the Prettier code formatter. We will also talk about alternatives to Prettier like JsFmt, StandardJS, EsLint + EditorConfig, and Beautifier. Hopefully you’ll take away something that you can use to improve your code formatting.

Brief Overview of Prettier

Prettier is a popular code formatter that can handle complex code structures and format your code in a readable way.

It operates on the principle of no configuration required and it's designed to produce readable, consistent code.

Prettier is an opinionated tool that encourages programmers to follow its formatting rules. It also parses the code and reprints it uniformly.

Why Explore Alternatives to Prettier?

There are many advantages of using Prettier. But like every other tool, exploring alternatives is sometimes a good idea. Here are some of the reasons for exploring alternatives to Prettier:

1. Inflexible style guides: Prettier adopts a strict set of formatting rules, and does not allow for much customization. Some programmers want a tool with a lot of configurations available.
2. Speed: Although Prettier is fast, you may need a tool that provides faster and better performance in large codebases or real-time formatting.
3. Language support: Prettier may not support (or might offer inadequate support) for the language you use.
4. More features: While Prettier is open source, you might prefer a paid code formatter that has more features and better integration with other tools.

In the guide, we will talk about four alternatives to Prettier. They are:

• JsFmt
• StandardJS
• ESLint+EditorConfig
• JS Beautifier

JsFmt Overview

JsFmt is a code formatter that uses esformatter as a formatting tool. It automatically reformats JavaScript code according to a set of predefined rules. It is available specifically to re-write, format, search, and validate JavaScript code.

To install JsFmt, run this command:

npm install -g jsfmt

A .jsfmtrc file, which can either be a JSON or INI formatted file, can overwrite any of the esformatter formatting options.

{
  "indent": 4,
  "line_ending": "unix",
  "quote": "single"
}

In this example, we specified the spaces for indentation to be four, we chose line-ending to be unix, and we picked single as the quote style for strings.

You can use the jsfmt rewrite method to change values in your JavaScript code. Here's an example of how to do that:

const x = 5;
const y = 10;
const z = x + y;
console.log(z);

//  The output will change to the below code after writing:  npx jsfmt --rewrite '5 -> 20' reduce.js

const x = 20;
const y = 10;
const z = x + y;
console.log(z);

To learn more about JsFmt, you can read its documentation here.

Features of JsFmt

1. Formating: JsFmt can format code according to a set of predefined rules.
2. Integrations: you can integrate JsFmt with popular code editors like Visual Studio Code, Sublime Text, and Atom, making it easy to format your code directly in your editor.
3. Command-line interface: JsFmt allows you to format your code as part of your build process or development workflow in the command line.

JsFmt Formatting Rules

Some of the formatting rules adopted by JsFmt are as follows

1. Set indent: With the --indent option, JsFmt indents your code with two spaces per level.
2. Quotes: In JsFmt, single quotes are the default for strings, but you can change this with the --double-quote option.
3. Wrapping: you can use --linene-width to change the default wrap lines setting in JsFmt.
4. Semicolons: JsFmt adds semicolons at the end of each statement by default. You can disable this using the --no-semi option.

Pros of JsFmt

1. Formatting, searching, and re-writing of JavaScript.
2. Customizable: JsFmt's flexibility makes it a popular choice for many development teams. It is a highly customizable tool that you can configure to match the specific requirements of a project.

Con of JsFmt

1. Lack of flexibility: despite the fact that it's customizeable, certain parts of JsFmt may not always be configurable to match the needs of your project.

StandardJS Overview

StandardJS is an open-source, no configuration linter, formatter, and JavaScript style guide. It checks the code for probable errors with the linter. It also formats code automatically, and helps you write code that is easy to read and understand.

It is the most popular option, coming in at 27,905 stars on GitHub clean code linter. It is also a powerful tool for ensuring the quality and consistency of your JavaScript code.

You can either install it globally or locally on your machine. To install globally, use the first command, while the second command is for installing locally. Note that to install it, you must have Node and npm installed on your computer.

To install globally: $ npm install standard --global

To install locally: $ npm install standard --save-dev

Alternatively, you can add StandardJS to the package JSON.

{
  "name": "my-cool-package",
  "devDependencies": {
    "standard": "*"
  },
  "scripts": {
    "test": "standard && node my-tests.js"
  }
}

The styles are checked automatically when you run the command:

npm test

To illustrate how it works, check the JavaScript code below:

let number = 10;
if (number == 10) {
  alert("yes");
} else {
  alert("no");
}

// The Output after running the npm test in the terminal

> test
> standard && node my-tests.js

standard: Use JavaScript Standard Style (https://standardjs.com)
  C:\Users\hp\Desktop\pretier\Js\script.js:5:5: Parsing error: Unexpected token else (null)

StandardJS shows that the code has a parsing error.

To fix most issues, run the following code:

standard --fix

Features of StandardJS

1. Community: A community of contributors guides the development of StandardJS by providing bug fixes and new features.
2. Linting: StandardJS linting catches style issues and programmer errors early.
3. Automatic code formatting: StandardJS get rid of messy and inconsistent code.
4. Command line integration: It has a command-line interface for running linter checks and auto-formatting code.

StandardJS Formatting Rules

Some of the widely used StandardJS formatting rules are listed below:

1. Indentation: StandardJS enforces a consistent indentation level of 2 spaces by default. To strictly implement this, you need to add the --fix option.
2. Line wrap: StandardJS doesn't enforce the rule of line length, but it recommends keeping lines shorter than 80 characters. Use $ myfile.js | standard --stdin to manually check the file length.
3. Semicolons: StandardJS recommends using semicolons for clarity and to avoid potential issues. But the tool doesn't enforce this. To enforce the use of semicolons, use this:

{
  "extends": "standard"
}

1. Spaces around operators: StandardJS recommends using spaces around operators, such as + and -, but it doesn't enforce this rule.

Pros of StandardJS

1. Zero configuration: No decisions to make. StandardJS is the easiest way to enforce code quality in your project.
2. Easy installation: StandardJS is easy to install, and you can use it with most editors and IDEs.
3. Enhances Productivity: StandardJS saves developers time and increases productivity by formatting code according to its rules.
4. Wide support: Most editors and IDEs support StandardJS using plugins and integrations.
5. Consistency: StandardJS promote consistency across projects by enforcing a strict set of coding rules.

Cons of StandardJS

1. Opinionated: Some developers may find the tool too opinionated. If that's the case, you might prefer to use other linting tools that allow for more customization.
2. Limited flexibility: StandardJS enforces a strict set of rules and conventions, which some developers may feel restricted by and prefer a more customizable approach.

ESLint + EditConfig Overview

ESlint provides configurable rules that you can tailor according to your specific project needs. It is one of the most popular JavaScript linter that analyzes programming errors, bugs, and suspicious constructs.

You can extend its functionality by adding plugins, which can provide custom parsers and extra rules.

You'll need Node installed on your before installing ESLint. To install it, use the command below:

npm init @eslint/config

Alternatively, you can create this manually on your machine:

npm install --save-dev eslint

For both installations, you need to have installed a package.json file. If not, run this command

npx eslint --init

The command will ask a series of questions about your project, coding style, and preferences to generate your configuration file.

You can run ESLint on any of your directories or files with this command:

npx eslint yourfile.js

Rules can be turned off and you can run the toolonly with basic syntax validation, as ESLint is configurable and flexible to your use case.

Once you have generated the configuration file, you can customize according to your needs. The configuration file is a JavaScript file that exports an object with the configuration settings.

For example, you can specify the rules you want, plugins to use, and environments for your code:

{
  "rules": {
    "semi": ["error", "always"],
    "quotes": ["error", "double"],
    "indent": ["error", 4]
  }
}

The semi, quotes, and indent are the names of the rules in ESLint, while the error level of the rule is the first value. There are only three outputs for the first values. They are:

• "off" or 0 - turn the rule off
• "warn" or 1 - turn the rule on as a warning (doesn’t affect exit code)
• "error" or 2 - turn the rule on as an error (exit code will be 1).

{
  "env": {
    "browser": true,
    "es2021": true
  },
  "extends": "eslint: recommended",
  "overrides": [],
  "parserOptions": {
    "ecmaVersion": "latest"
  },
  "rules": {
    "indent": ["error", 4],
    "quotes": ["error", "single"],
    "semi": ["error", "never"]
  }
}

In this example, you specify that your code should run in a browser environment. Enable ECMAScript 2018 syntax, and follow the ESLint rules. You've also enabled three specific rules: indent, quotes, and semi.

The indent rule determines that an alert error will be thrown if indentation is more than 4 spaces. Likewise if you use double-quotes instead of single, there will be an error. You also specified not to use semi-colons.

To fix most of the issues in ESLint, use this command:

npx eslint yourfile.js --fix

Here's an example:

const numbers = [1, 3, 5, 2, 6, 78, 8];
let peoples = ["shola", "kamal"];
console.log(peoples);

// The output

 error  'numbers' is assigned a value but never used  no-unused-vars
   error  Extra semicolon                               semi

✖ 2 problems (2 errors, 0 warnings)
  1 error and 0 warnings potentially fixable with the `--fix` option.

EditorConfig Overview

EditorConfig is an open-source file format. It provides standard ways of defining and maintaining coding styles in a project.

It maintains consistent coding styles which is especially useful when you have many developers working on the same project across various editors and IDEs. The tool consists of a collection of text editor plugins that enable editors to read the file format and adhere to defined styles.

You'll need to create a file named .editorconfig in the directory. EditorConfig plugins will look for the file in the directory of the opened file and on every parent directory.

Files are read from top to bottom, and a search for .editorconfig files will stop if the root file path is reached.

Creating an EditorConfig file is straightforward. Open a new file, and save it with .editorconfig as shown below.

Inside the .editorconfig file, the following wildcard patterns are used:

root = true

[*]

indent_size = 4
indent_style = space
end_of_line = lf
insert_final_newline = true

 // Set root to true: A search for .editorconfig files will stop if the root file path is reached or an EditorConfig file with root=true is found.

 //[*]: Except for path selectors, it matches any string of characters.

 //indent_size: Indent size is set to 4. 
 //Indent_style: set to space
 //end_of_line: Set to lf
//insert_final_newline: Set to true

To know more about the wildcards pattern, visit the EditorConfig docs.

Using ESLint and EditorConfig together can help to spot potential issues early. It also ensures that your code is consistent, maintainable, and of high quality.

The combination of ESLint and EDitorConfig saves you time on code maintenance and debugging.

Features of ESLint

1. Configurable: ESLint allows you to customize and add your own rules to the configuration file.
2. Support ECMAScript: ESLint ensures your code is compatible with the latest language features.
3. Supports many file formats: ESLint can analyze JavaScript code in a variety of file formats, including but not limited to .js, .jsx, and .vue.
4. Integration: ESLint integrates seamlessly with Webpack and Gulp, which are popular build tools.

ESLint Formatting Rules

Some of the popular formatting rules in ESLint are listed below:

1. Indentation: ESLint by default expects a four-space per level indent. But you can customize this using the popular --fix option.
2. Semicolons: ESLint enforces the use of semicolons at the end of each statement. This rule is set to "always" by default. Use the popular --fix option to reset it to "never".
3. Line wrap: Use the max-len rule to change the maximum line length from the default 80 to your preferred value.
4. Quotes: The quotes rule can be changed from the default value of "single" to "double" using the --fix option.

Pros of ESLint

1. Saves time: ESLint saves time by reducing the amount of time spent on manual code reviews and debugging.
2. Active Community: ESLint has a wide and active community base that contributes to the development of the tool and its ecosystem.
3. Code analyzer: ESLint analyze your code to quickly find problems.
4. Consistency: ESLint helps in maintaining clean and readable code by enforcing a consistent coding style.

Cons of ESLint

1. Rule conflicts: With a large set of rules, ESLint rules can sometimes conflict with one another, resulting in more configuration and fine-tuning.
2. Steeper learning curve: ESLint has a pretty steep learning curve, as it has many rules and learning how to configure them can take time.
3. False positives: ESLint can sometimes flag code as problematic code even when it is correct, which can be frustrating for developers.

Overview of JS Beautifier

JavaScript Beautifier, also known as js-beautify, is an open-source, cross-platform command-line tool. It is a beautifier for re-formating and re-indenting bookmarklets, ugly JavaScript, and it partly deobfuscates scripts.

You can install JS beautifier both locally and globally.

Run npm -g install js-beautify to install globally, and npm install js-beautify to install locally.

You can configure it through the command line option.

After local installation, you can import and call the appropriate beautifier methods for JS, CSS, or HTML. An example of how to call the methods goes like this: beautify (code, options).

While code is the string of code to be beautified, options is an object with the settings you would like used to beautify the code. See the example below for a JavaScript script file:

npx beautify("script.js",{indent_size:4})

You can also configure it through a configuration file:

{
  "indent_size": 4,
  "indent_char": " ",
  "indent_with_tabs": false,
  "brace_style": "collapse"
}

Create a file .jsbeautifyrc in the root directory of your project. This option will override the default option of JS beautifier. You can also use Beautifier on your web browser. Learn more about JSbeautifer from its docs here.

Feature of JS Beautifier

1. Formatting: You can customize JS Beautifier to fit your personal preferences and coding style because it offers varieties of formatting options, such as indentation size and braces style.
2. Online version: You can beautify JavaScript using JS Beautifier in your web browser, just as you can on the command line.

JS Beautifier Formatting Rules

1. Indentation: The default identation in JS Beautifier is 4 spaces, but you can change it to 2 or 8 spaces, or use tabs instead. Use the indent_size option to specify the number of spaces to use for indentation.
2. Semicolons: You can change your semicolon settings in JS Beautifier with the semicolon option. You change this by alternating the value of the semicolon option between "true" or "false".
3. Line wrap: Use the max_char option to limit each line to 80 characters. You can set the value of the max_char to 80 or any other preferred number.

Pros of JS Beautifier

1. Time-saving: JS Beautifier saves time. It automates the many steps of formatting and organizing code.
2. Online presence: JS Beautifier's online presence is a game changer, as a lot of non-developers will be able to use it.
3. Detects errors: JS Beautifier helps catch small errors that can be difficult to spot otherwise.
4. Integration: JS Beautifier's compatibility with varieties of code editors and IDEs makes it a versatile tool.

Cons of JS Beautifier

1. Complexity: Despite having an online version, JS Beautifier is somewhat complex for beginners.
2. Potential for over-formatting: In some cases, JS Beautifier may make the code harder to read because of over-formatting.

Results from all the Formatting Tools

We'll use the code sample below to test how these four popular tools format code:

const numbers = [2,3,8,9,7]

          let peoples = ['kamal', 'lawal', "shola", "olaide"];

As you can see, this code isn't properly formatted. So let's try the tools to see how they help.

Formatting example with JsFmt

Using the above code as a sample, the command npx jsfmt --write "Your file" will format the code to this:

const numbers = [2, 3, 8, 9, 7]

let peoples = ['kamal', 'lawal', "shola", "olaide"];

As you can see, there is a noticeable change in the code, and you can configure this to your desired taste.

Formatting example with StandardJS

By running the popular npx standard--fix command from the terminal, you will have the following result.

const numbers = [2, 3, 8, 9, 7]

const peoples = ['kamal', 'lawal', 'shola', 'olaide']

Notice the code was properly formatted, most especially the elements with double quotes within the peoples array.

Formatting example with ESLint

Using the same code as above, the npx eslint "Your file name --fix" command will quickly format to this:

const numbers = [2,3,8,9,7]

let peoples = ['kamal','lawal','shola','olaide']

You can also change the configuration of the tool, by changing the elements of the peoples array so they're inside double quotes:

const numbers = [2,3,8,9,7]

let peoples = ["kamal","lawal","shola","olaide"];

You can do this by going to the .eslintrc file and manipulating the rules like this:

{
  "quotes": ["error", "double"],
  "semi": ["off", "always"]
}

Formatting example with JS Beautifier

Here's the result from JS Beautifier for the same code:

const numbers = [2, 3, 8, 9, 7]
let peoples = ['kamal', 'lawal', "shola", "olaide"];

You can configure it more from your JSON file if you wish.

Now you've seen these formatters in action!

Conclusion

In this guide, we talked about some alternatives to using Prettier. We discussed Jsfmt, ESlint, StandardJS, and JS Beautifier, as well as their features, pros, and cons.

I hope you are now more equipped to choose the right linter/formatter for your coding projects.

One way to avoid this is to simplify your code. This can help improve its readability, efficiency, and maintainability.

This article will discuss ten ways to simplify your JavaScript code, making it more readable and maintainable. Let’s jump right in!

Use Arrow Functions

Using Arrow functions is a shorthand way for creating functions in JavaScript. They simplify your code by reducing the boilerplate needed to define a function.

For example, instead of using the function keyword to define a function like this:

function greeings(name){ 
console.log(Hello, ${name}!);
}

You can use an arrow function like this

const greeting = name => console.log(`Hello, ${name}!`);

Apart from arrow functions having a shorter syntax, they can make your code more concise, easier to read, and less error-prone. This makes it a better choice than using the function keyword

Use Descriptive Variable Names

Using descriptive variable names can make your code more readable and easier to understand. This is much better than using single-letter variable names or abbreviations, as it may not be immediately clear to someone else reading your code what those variables mean.

For example, instead of using:

const x = 10;

Use this:

const numberOfItems = 10;

numberOfItems is much more descriptive than x and will help you (or other developers looking at your code) understand what it's doing.

Use Functional Programming

Functional programming prioritizes the use of pure functions and immutable data structures. Using functional programming techniques can help simplify your code greatly and reduce the risk of bugs and side effects.

For example, instead of modifying an array in place:

const numbers = [1, 2, 3];
numbers.push(4);

You can use the spread operator to create a new array:

const numbers = [1, 2, 3];
const newNumbers = [...numbers, 4];

Using the spread operator helps you prevent unexpected side effects and makes your code more predictable.

When you modify the function in place, you change the original array or object, If another part of your code is relying on that array or object, then it can lead to bugs and unexpected behavior.

On the other hand, using the spread operator creates a new array or object, leaving the original intact. This makes your code more predictable and easier to reason about.

Avoid Nesting Code

Nesting code can make it difficult to read and understand. A better way is to try to flatten your code as much as possible. You can do this by using early returns, ternary operators, and function composition.

For example, instead of nesting if statements:

if (condition1) {
  if (condition2) {
    // code
  }
}

Use early returns:

if (condition1) {
  return;
}
if (condition2) {
  return;
}
// code

Using early returns here makes our code is more readable and easier to understand because it breaks down each condition into a separate if statement, and returns early if any condition fails.

Early returns can also increase the efficiency of your code by preventing unnecessary computations.

Use Default Parameters

Using default parameters allows you to specify a default value for a function parameter. This can simplify your code by reducing the number of conditional statements you need to write.

For example, instead of using conditional logic to set a default value:

function greet(name) {
  if (!name) {
    name = 'World';
  }
  console.log(`Hello, ${name}!`);
}

You can use a default parameter:

function greet(name = 'World') {
  console.log(`Hello, ${name}!`);
}

Using a default parameter provides you with a simple way to set default values. But not only that, it makes your code more flexible, less error prone, and also makes your code easier to understand.

Use Destructuring

Destructuring allows you to extract values from arrays and objects and assign them to variables. Doing this can make your code more concise and easier to read.

For example, instead of accessing object properties directly like this:

const person = { name: 'John', age: 30 };
const name = person.name;
const age = person.age;

You can use destructuring:

const { name, age } = { name: 'John', age: 30 };

Using destructuring would be much better than accessing object properties as it helps you quickly understand the purpose of the code, especially when working with complex data structures. It also helps reduce the amount of code you need to write, provides flexibility, results in cleaner code, and also helps avoid naming conflicts

Use Promises

Promises allow you to write asynchronous code in a more readable and predictable way. They simplify your code by avoiding the need for callbacks and enabling you to chain asynchronous operations together.

For example, instead of nesting callbacks:

function getUserData(userId, callback) {
  getUser(userId, function(user) {
    getPosts(user, function(posts) {
      getComments(posts, function(comments) {
        callback(comments);
      });
    });
  });
}

You can use promises like this:

function getUserData(userId) {
  return getUser(userId)
    .then(user => getPosts(user))
    .then(posts => getComments(posts));
}

Using promises instead of nesting callbacks can makes the code more concise and easier to read, especially when working with complex asynchronous operations.

Use Array Methods

JavaScript has many built-in methods for manipulating arrays, such as map, filter, reduce, and forEach. Using these methods can make your code more concise and easier to read.

For example, instead of using a for loop to iterate over an array:

const numbers = [1, 2, 3];
for (let i = 0; i < numbers.length; i++) {
  console.log(numbers[i]);
}

You can use the forEach method:

const numbers = [1, 2, 3];
numbers.forEach(number => console.log(number));

Using array methods over traditional for loops can make your code more concise, readable, and modular, while also providing better error handling and supporting functional programming techniques.

Use Object Methods

JavaScript objects provide a variety of built-in methods, such as Object.keys, Object.values, and Object.entries. These methods can make your code simpler by reducing the need for loops and conditionals.

For example, instead of using a for loop to iterate over an object:

const person = { name: 'John', age: 30 };
for (const key in person) {
  console.log(`${key}: ${person[key]}`);
}

You can use the Object.entries method:

const person = { name: 'John', age: 30 };
Object.entries(person).forEach(([key, value]) => console.log(`${key}: ${value}`));

Just like the array methods, using object methods can make your code more concise, readable, and modular.

Use Libraries and Frameworks

JavaScript has a wide variety of modules and frameworks that may help you create simpler code with less boilerplate.

Examples include React for building user interfaces, Lodash for functional programming, and Moment.js for working with dates and times.

You might consider using a framework/library when:

• When you want to build a complex application with functionalities that can be achieved with a library or framework.
• When you have a tight timeline and need to deliver your project quickly.
• When you want to improve your code's quality and reduce maintenance costs over time.

On the other hand, you may also want to avoid using a framework/library when:

• When your project requirements are simple and require no external tools.
• When you want to have control over your code and avoid dependencies on external tools.

Wrapping Up

Simplifying your code can make it more readable and maintainable. By following these tips, you can write code that is easier to understand and more efficient.

What other tips would you suggest? Don't forget to share if you found this helpful.