Guidelines
Files and Directories

Files and Directories

Organize your files around responsibility

Organizing your files around responsibility can help improve the maintainability and collaboration within a team, as well as the reusability and flexibility of the code.

This type of structure reflects the purpose and role of each file within the overall architecture of the application, which can make it easier to understand and modify the codebase, as well as adapt the project to changing requirements or technologies.

.
└── src
    └── modules
        β”œβ”€β”€ product
        β”‚   β”œβ”€β”€ index.js
        β”‚   β”œβ”€β”€ product.controller.js
        β”‚   β”œβ”€β”€ product.model.js
        β”‚   └── product.test.js
        └── user
            β”œβ”€β”€ index.js
            β”œβ”€β”€ user.controller.js
            β”œβ”€β”€ user.model.js
            └── user.test.js

Use a consistent naming convention for files and directories

Use a consistent naming convention for files and directories for your project. Specially on project with developers using both POSIX and Windows systems since Windows is a case-insensitive operating system.

To avoid case issues with files and directories naming, you can follow these best practices:

  • Stick to a naming convention: It is important to agree on a consistent naming convention for files and directories within the project, and to stick to it consistently. For example, you might decide to a use kebab-case file naming convention to avoid using uppercase and spaces.
  • Use .gitattributes to ignore case: You can use a .gitattributes file to specify that certain files and directories or patterns of files and directories should be treated as if they were the same, regardless of the case. This can help prevent conflicts when merging changes from different developers.
  • Configure Git to ignore case: You can set the core.ignoreCase configuration option in Git to true, either globally or per-repository. This will cause Git to treat files and directories with the same name but different capitalization as if they were the same.
  • Communicate with your team: It is important to communicate with your team and make sure everyone is aware of the conventions that have been agreed upon. This can help prevent issues from arising in the first place.

By following these best practices, you can help ensure that your project is able to handle files and directories with different capitalization in a consistent and predictable way, regardless of the operating system being used.

Keep your file structure flat

Keeping your file structure flat can help improve the organization and maintainability of your project, as it reduces the need for deep nesting of directories and can make it easier to locate and access the files you need. This can also make it easier for other developers to understand and work with your project, as the structure is more straightforward and intuitive.

Of course, there are also situations where a more deeply nested file structure may be appropriate, such as when you have a large project with a complex codebase and a clear hierarchy of modules or components. In these cases, it may make sense to use a more nested file structure to help organize and structure your code.

Ultimately, the best approach will depend on the specific needs of your project. It is a good idea to carefully consider the trade-offs and decide on a file structure that is both effective and maintainable for your project.

Use UTF-8 for files encoding

The preferred file encoding is usually UTF-8. UTF-8 is a character encoding standard that represents most of the world's written languages in a single byte-oriented encoding. It is widely used as the default character encoding for the World Wide Web and other Internet-based applications, and is supported by most modern web browsers and operating systems.

Use standardized files extensions

In some cases, a file type may have multiple extensions that are all commonly used to identify that type of file. For example, JPEG files can be saved with the .jpg, or .jpeg, extension.

Using multiple extensions for the same file type can be confusing for developers, as it is not always clear which extension is the correct one to use. Using standardized files extensions can help to ensure that everyone on a project is using the same conventions and that everyone can easily identify the types of files they are working with.

Here is a list of file types that can have multiple possible extensions, along with the proposed standard extension. You and your team can customize this list to meet your specific needs and preferences.

File typeExtensionsStandard
GraphQL.gql, .graphql.gql
HTML.html, .htm.html
JPEG.jpeg, .jpg.jpg
Markdown.md, .mdown, .markdown.md
Sass.sass, .scss.scss (prefer free-form syntax)
TIFF.tif, .tiff.tiff
YAML.yaml, .yml.yaml

Use standardized directories

Using standardized directories can help improve the organization and maintainability of your project, as it allows developers from any horizon to easily locate and understand the purpose of different parts of the codebase based on the directory names.

Here is a list of the common standardized directories used by the developer community:

  • src: Contain the source code for your application or library. It may include subdirectories for different parts of the codebase, such as components, models, views, etc.
  • dist or build: Contain the built or compiled version of your code, which is ready for deployment or distribution. It may include minified or optimized versions of your source code, as well as any assets or resources needed by your application.
  • public: Contain static assets or resources that are needed by your application, such as images, fonts, or other media. These assets may be served directly to the client without any processing or transformation.
  • test or tests: Contain the common tests and testing tools for your application or library. It may include unit tests, integration tests, and other types of tests and toolings that are used to validate the global behavior and functionality of your code.
  • scripts: Contain utility scripts or build scripts that are used to automate tasks such as building or deploying your code.
  • config: Contain configuration files or settings for your application or project. These configuration files can be written in various formats and can contain any type of data that is relevant to the application's configuration except sensitive information.
  • docs: Contain documentation for your project, such as user guides, API reference materials, or technical specifications. The purpose of this directory is to provide detailed information about the project, its features, and how to use it.
  • examples: Contain example code or usage scenarios that demonstrate how to use your application or library. These examples may be used to help users understand and learn how to use your code.
  • vendor: Contain third-party libraries and dependencies that are needed by your project but not available via npm. Contrary to the npm dependencies, these libraries and dependencies are committed to version control.
Last updated on