1.3 Naming Conventions & Documentation

React is an unopinionated library. It does not dictate how you should name your functions, structure your files, or document your code. While this freedom is great, it can quickly lead to a messy, unmaintainable codebase when multiple developers work on the same project without a shared pattern.

Establishing a strict naming convention and documentation standard ensures your codebase remains clean, predictable, and easy to scale.

---

1. Why Do Naming Conventions and Documentation Matter?

Adopting a uniform team standard yields significant architectural advantages:

• Enhanced Maintainability: A unified pattern prevents team members from writing conflicting structures (e.g., one developer using camelCase for files while another uses PascalCase), ensuring a well-structured project.

• Self-Explanatory Code: Files, components, and services become identifiable at a glance. You instantly know a file's purpose just by looking at its name.

• Accelerated Debugging: If you encounter a bug on a specific screen, finding the responsible UI files, services, or helper utilities takes seconds rather than minutes of manual hunting.

• Seamless Onboarding: New developers can integrate into the team faster without constantly asking peers how to name files or interpret complex business logic.

• Elimination of Duplicate Code: Predictable naming patterns make existing functions discoverable, naturally preventing developers from accidentally recreating utilities that already exist.

---

2. Directory & Folder Naming Rules

• Rule: Always use lowercase and plural names for directories.

• Convention: Use single-word names or standard lower-case structures. Avoid capital letters to maintain clear separation from component filenames.

• Cross-OS Compatibility: Operating systems like Linux and macOS are case-sensitive (/Components and /components are separate folders), whereas Windows treats them as identical. Standardizing on lowercase eliminates subtle cross-platform import bugs.

📁 src
 ├── 📁 components    (Plural & lowercase - hosts multiple UI pieces)
 ├── 📁 pages         (Plural & lowercase - hosts screen views)
 ├── 📁 services      (Plural & lowercase - hosts API layers)
 ├── 📁 utils         (Plural & lowercase - hosts helper utilities)

Examples

• Good: components, pages, hooks, services, utils

• Bad: Component (singular & capitalized), Test123, NewFolder, helper_files

---

3. File & Component Naming Rules

File naming splits into two categories based on whether the file contains UI layouts or plain JavaScript/TypeScript logic.

UI Components and Pages

• Rule: Use PascalCase and ensure names are descriptive and meaningful.

• Why? React demands that components begin with a capital letter to differentiate them from standard HTML tags (which are always lowercase). Aligning your file names with component names keeps your project highly intuitive.

// Good: PascalCase & Descriptive (AdminLoginForm.jsx)
export const AdminLoginForm = () => {
  return <form>{/* Admin login fields */}</form>;
};

// Bad: Generic or incorrect casing
export const login = () => {}; // Lowercase looks like an HTML tag or utility
export const AdminLogin1 = () => {}; // Arbitrary numbering

Non-UI Files (Services, Helpers, Utilities)

• Rule: Use camelCase for files containing vanilla logic. Use plural forms only if the file exports a collection of items (like validations).

// Good: camelCase for non-component files
// src/services/adminService.js
// src/utils/validations.js

// Bad: Looks like a component due to PascalCase
// src/services/AdminService.js 

---

4. Variables & Functions Naming Rules

Variables

• Rule: Use camelCase and ensure names are descriptive.

• Boolean Rule: Prefix boolean flags with clear question-based indicators such as is, has, can, or should. This instantly identifies the variable as a true/false switch.

// Good
const username = "John";
const totalPrice = 500;
const isLoading = true;    // Instantly recognized as boolean
const hasError = false;    // Instantly recognized as boolean

// Bad
const user1 = "John";
const loading = true;      // Vague: Is it a state string or a boolean flag?
const admin_login = true;  // Inconsistent casing style

Functions

• Rule: Use camelCase starting with a verb to describe the action the function performs.

// Good
const getUserData = () => {};
const calculateTotalPrice = () => {};
const fetchProducts = () => {};

// Bad
const doTask = () => {};   // Vague: What task is it executing?
const userData = () => {}; // Named like a variable instead of an action

---

5. Inline Documentation Standards

Documenting complex files, handlers, and components saves hours of reverse-engineering down the line. A clean way to manage this is through standardized comment headers.

Component Header Example

/**
 * @component AdminLoginForm
 * @description Responsible for rendering the Admin Login UI and managing form validation logic.
 */
export const AdminLoginForm = () => {
  return <div>Admin Login Form</div>;
};

Service/Function Header Example

/**
 * @function adminLogin
 * @description Dispatches credentials to the authentication server to verify admin status.
 * @param {string} email - The input corporate email address.
 * @param {string} password - The raw input password string.
 * @returns {Promise} Resolves with network auth payload.
 */
const adminLogin = (email, password) => {
  return new Promise((resolve) => {
    // Auth network logic goes here
  });
};

Pro Tip: Avoid blindly copy-pasting code block headers without updating the names. If a function header contains a mismatched name, it shows that the documentation was copied carelessly and cannot be trusted by the team.

---

💡 Interview Q&A (Simple English)

Q1: React doesn't force us to use any specific naming rules, so why should we care about them? Ans: React gives you total freedom, but if a team doesn't agree on a shared pattern, the codebase quickly becomes messy. Using consistent rules keeps the project organized, makes it simple to maintain, helps find files faster, and ensures multiple developers can collaborate without creating chaotic code styles.

Q2: Why do we name folder structures in lowercase, but UI components in PascalCase? Ans: This makes a clear visual boundary in your project. Folders stay lowercase to act as generic containers. UI Components use PascalCase (Capital letters) because React explicitly treats capitalized tags as custom components and lowercase tags as standard HTML elements (like <div> or <button>).

Q3: Why should we prefix boolean variables with words like is, has, or can? Ans: It makes the variable self-explanatory. If you name a variable loading, it isn't instantly clear if it holds a string message or a true/false state. But if you name it isLoading, anyone reading the code instantly knows it is a boolean value that is either true or false.

Q4: What should be included when documenting a JavaScript function or React component? Ans: You should clearly document the Name of the function, a brief Description of what it actually does, the Parameters (inputs) it expects along with their data types, and what it Returns (outputs). This allows other developers to safely interact with your code without reading through the whole internal implementation.