Naming files and directories in JavaScript projects
Tags: javascript, programming, discuss, react
Published: 2022-04-30 06:49:39

## A brief story of naming in a project

### Getting started

File names start out easy:

* `app.js`
* `utils.js`


Directory names also often start out easy:

* `/components/`
* `/utils/`

### Add a utility file with multiple functions

Let's add a utility file named "product utils". This is where things start to get hard.

* `product-utils.js`
* `productUtils.js`
* `ProductUtils.js`

There is no particular guideline to follow here, so let's choose `product-utils.js` for now.

### Add a utility file with a single function

Next we need to create a utility file that contains a single function named `calculateSalary`.

What to name this file?

And do we use a default export or not, since its just one function?

* `calculateSalary.js`
* `calculate-salary.js`

Here `calculate-salary` feels strange since the function is named `calculateSalary`, so lets go with `calculateSalary.js`.

```js
import calculateSalary from "./calculateSalary";
```

However, now we have `calculateSalary.js` and `product-utils.js`. Should we rename `product-utils.js` to `productUtils.js`? That also feels strange since the product utils file contains many functions? Let's leave as-is for now.

### Add a React component

Next we need to add a React component named `ProductCard`.

Easy, that file should be named `ProductCard.js` and the component is the default export.

However we're starting to get a mix of naming conventions now, which feels uncomfortable, but also kind of makes sense.

And what about when new people join the team? That's OK, we'll just teach them the convention, easy.

### Export a utility function from a React component file

Our React component file has the component as the default export, so let's make the utility function in that file a regular _non default_ export.

So we'll have:

```js
import ProductCard, { makeProductPrice } from "components/ProductCard"
```

### Our React component is growing

Our Product Card is getting a bit bigger, and need to be split into multiple files, so we'll need to move it to it's own directory now. What to name that directory?

How about `/ProductCard/`? That matches the component name and no need to change import statements, but is different from other directory names.

How about `/product-card/`? It's a nice generic name, but it means our imports "from ProductCard" will all need to change.

And what about `/productCard/`? Also a nice generic name, but no particular reason to use this for a React component.

Let's go with `/ProductCard/`.

### Our Product utils are growing

Our `product-utils.js` file is growing now and need so be split into multple files, but we want to put them into a directory. What to name that directory?

How about `/ProductUtils/`? Nope, that's the convention for component directories.

How about `/product-utils/` or `/productUtils/`? Time to roll some dice 🎲 🎲 🎲 and `/productUtils/` is the winner 🎉.

### New developer joins the team 🎉

A new person joins your team. Unfortunately nobody has time to explain the conventions. They sees variety of different naming strategies. They've used a completely different naming strategy in their previous project. They [decide to apply their own conventions to the naming](https://blog.codinghorror.com/the-broken-window-theory/). Awesome 🙌.

## A Possible Solution

Let's review what happened in this project.

In most cases the file or directory name was influenced by its content. We have a lot of different kinds of content, so we end up with many different kinds of names.

Ideally a good naming system should be **intuitive**, but most of all **simple**.

So maybe we can look at this from a different perspective, consider an _abstraction_ for our files and directories:

- Consider that all directories are the same kind of thing.
- Consider that all files are the same kind of thing. Fortunately they are already the same kind of thing; a _module_.

### File naming

First, if we consider that **all** files are modules, then we can base our naming on that.

Second, to keep things simple, consider that modules are _containers_ and you only access the contents via the container, meaning _no default exports_.

You can choose any naming convention you prefer, providing **all files use the same naming convention**.

### Directory naming

Directories are already containers.

So you may like to use the same naming convention as you did for files.

However what's important is that **all directories use the same naming convention**.

### An Example

Considering the scenarios above, here is what your code may start to look like.

Using _PascalCase_ for both directories and files.

```js
import { App } from "App";

import {
  ProductCard,
  makeProductPrice
} from "Product/Components/ProductUI";

import {
  calculateSalary
} from "Payroll/SalaryCalculator";

import {
  findProductsOnSale,
  calculateProductPrice,
} from "Product/ProductUtils";
```

Or using _camelCase_ for both directories and files.

```js
import { App } from "app";

import {
  ProductCard,
  makeProductPrice
} from "product/components/productUi";

import {
  calculateSalary
} from "payroll/salaryCalculator";

import {
  findProductsOnSale,
  calculateProductPrice,
} from "product/productUtils";
```

Using _kebab-case_ for both directories and files.

```js
import { App } from "app";

import {
  ProductCard,
  makeProductPrice
} from "product/components/product-ui";

import {
  calculateSalary
} from "payroll/salary-calculator";

import {
  findProductsOnSale,
  calculateProductPrice,
} from "product/product-utils";
```

Objectively it's a simple strategy that anyone can apply.

If you are also using ESLint or TypeScript, then you have an additional benefit where if you rename a function or component in a file, then you'll be prompted to rename your imports as well, keeping consistent naming everywhere and keeping them searchable.

### This is a stylistic matter

This is not really a naming discussion per se, it's really a stylistic discussion which is subjective so it can frequently lead to [bike shedding](https://en.wikipedia.org/wiki/Law_of_triviality).

In matters of subjectivity if you're able to find a simple guideline, and then follow it independent of personal preferences it can [eliminate a whole category of discussions](https://prettier.io/), leaving time for more important matters.