Folder and File Naming Conventions Go Wild

Throughout my career, I've encountered numerous conventions and strategies for organizing, naming, and structuring folders and files to enhance maintainability and comprehension. Here's a little spoiler: there's no one-size-fits-all solution, and earnestly seeking the perfect one is futile. Instead, focusing on consistency is key. You can always iterate and adjust your structure later if necessary, but enforcing consistency can be more challenging.

The Problem

Indeed, many developers overlook the fact that without documentation or adequate knowledge transfer, newcomers can easily feel disoriented, akin to lost children in a cornfield. So, when encountering a folder and file structure like below, I can guarantee you that without any documentation of good knowledge transfer, the names for folders/files will be 100% randomly created by every developer...

src/
  components/
    HeaderComponent/
      HeaderComponent.js
      HeaderComponent.css
    FooterComponent/
      FooterComponent.js
      FooterComponent.css
  pages/
    HomePage/
      HomePage.js
      HomePage.css
    AboutPage/
      AboutPage.js
      AboutPage.css
  utils/
    apiUtils.js
    validationUtils.js
  App.js
  index.js

Solution: The Consistency

Consistency is paramount when developing software, in my opinion. Without it, your project can quickly descend into chaos, leaving everyone but you, the author, bewildered. When you're the sole developer, you might get away with doing things your way. However, when others join the project, problems inevitably arise.

Maintaining consistency resolves myriad issues, eliminating the need for incessant communication back and forth and averting countless time-wasting scenarios.

src/
  components/
    header_component/
      header_component.js
      header_component.css
    footer_component/
      footer_component.js
      footer_component.css
  pages/
    home_page/
      home_page.js
      home_page.css
    about_page/
      about_page.js
      about_page.css
  utils/
    api_utils.js
    validation_utils.js
  app.js
  index.js

Many seasoned developers grasp the significance of time, recognizing that constantly explaining why a folder should be named NameOfTheFolder instead of name-of-the-folder is a substantial waste of time.

Consequences: Are They Justified?

The primary argument for employing various naming conventions is the ability to quickly discern the purpose of a file. However, I find this rationale unconvincing. Instead, the central concept is to adopt a consistent approach, such as naming React components as ReactComponentsInThisWay.tsx, and other files similarly, like some-utility-file.js.

I see your point, but let's consider this: when you encounter a variable in the codebase, what's more important for understanding its purpose - the naming convention or the variable's actual name?

const my_var = 5;
const MY_VAR = 5;
const myVar = 5;
const __my_var__ = 5;
const maxUsers = 5; // This is important

Certainly, there are instances where conventions are highly practical, such as distinguishing variables added to the window object by third-party libraries. These conventions serve to mitigate the risk of overrides and ensure smooth interoperability within the ecosystem.

window.__NEXT_APP_ID__

Employing conventions solely for aesthetic appeal without practical justification only adds unnecessary complexity. Conventions, much like design patterns, should be applied where they provide clear benefits and solve specific problems. They shouldn't be enforced arbitrarily. If enforcement is necessary, proper documentation or integration with automation tools like ESLint, Prettier, Sonar, or others can ensure consistency.

Opinion

After trying out several options, I've found that kebab-case is the one I consistently use at the beginning of every project.

src/
  components/
    header-component/
      header-component.js
      header-component.css
    footer-component/
      footer-component.js
      footer-component.css
  pages/
    home-page/
      home-page.js
      home-page.css
    about-page/
      about-page.js
      about-page.css
  utils/
    api-utils.js
    validation-utils.js
  app.js
  index.js

I use kebab-case for both folders and files. It's quick to write (no uppercase letters), and there are no issues with Git when changing the name. Sometimes, using uppercase letters can cause Git to behave erratically.

In my pipeline, I employ a custom script that checks file names for consistency and throws exceptions if any file deviates from the specified naming convention. This ensures uniformity across the project.

Summary

Consistency greatly simplifies a developer's life. It allows you to focus your mental energy on tasks that truly matter, rather than constantly grappling with inconsistencies. Amidst the ever-changing landscape of new JavaScript frameworks, adhering to a consistent structure provides stability and clarity.

Moreover, consistency saves significant time in communication, and maintenance, and eliminates the need for extensive knowledge transfer sessions. Remember, fewer rules mean less discussion, documentation, and cognitive load.

Rules serve a purpose, but excessive rule-making borders on fanaticism. Finding the right balance is key to fostering efficiency without stifling creativity.