How to Design a Project Directory Structure: Best Practices for Code and Resource Files

A clear and well-organized directory structure not only improves team collaboration but also enhances the maintainability of a project. This article provides a complete guide on how to design a project directory structure, covering where to store code, configuration files, resource files (like fonts and data files), and principles to follow.

1. Basic Directory Structure

Here is an example of a typical project directory structure:

project/
  ├── src/                  # Main source code
  │    ├── main.py          # Main entry point
  │    ├── utils.py         # Utility module
  │    └── modules/         # Submodules
  ├── data/                 # Static data files (e.g., input or reference data)
  │    ├── namelist.csv     # Name list file
  │    └── sample_data.json # Example data
  ├── output/               # Output files generated by the program
  │    ├── processed.csv    # Processed data
  │    ├── video.mp4        # Output video
  ├── config/               # Configuration files
  │    ├── settings.yaml    # Main configuration file
  │    └── db_config.json   # Database configuration
  ├── assets/               # Static resources (e.g., fonts, images, audio)
  │    ├── fonts/           # Font files
  │    │    └── Monan.ttf
  │    └── images/          # Image files
  │         └── logo.png
  ├── tests/                # Test files
  │    ├── test_namelist.csv # Test data files
  │    └── test_main.py     # Test code
  ├── logs/                 # Log files
  │    └── app.log          # Application logs
  ├── README.md             # Project description
  └── requirements.txt      # Dependency list

2. Purpose and Contents of Each Directory

src/: Main Source Code

This directory contains the core logic and modules of the project, typically including:

• main.py: The main entry point for the project.
• Utility modules: For example, utils.py, which stores helper functions.
• Submodules: To organize complex logic, stored under subdirectories like modules/.

Example Code: main.py

import sys
import os
# Add the project root directory to sys.path for easier module imports
sys.path.append(os.path.dirname(os.path.abspath(__file__)))
# Import utility module
from utils import some_utility_function
if __name__ == "__main__":
    some_utility_function()

data/: Static Data Files

Stores static input data or reference files, such as CSV or JSON files.

• Example: namelist.csv for storing user lists.
• Suitable for immutable data like initial parameters or test datasets.

output/: Output Files

Stores files generated by the program during execution, such as processed data, videos, or images.

• Example: processed.csv for processed data, video.mp4 for generated videos.

Example Code for Generating Output Files:

import pandas as pd
import os
# Define output directory
output_dir = "output/"
os.makedirs(output_dir, exist_ok=True)
# Save results
result_df = pd.DataFrame({"Name": ["Alice", "Bob"], "Age": [25, 30]})
result_df.to_csv(os.path.join(output_dir, "processed.csv"), index=False)
print("Results saved to output/processed.csv")

config/: Configuration Files

Stores files that control the program’s behavior, such as:

• settings.yaml: Main application settings.
• db_config.json: Database-related configurations.

Example Code for Reading Configuration Files:

import yaml
# Load configuration
with open("config/settings.yaml", "r") as f:
    config = yaml.safe_load(f)
print(config)

assets/: Static Resource Files

Stores static resources used in the project, such as:

• Font files: e.g., fonts/Monan.ttf.
• Image files: e.g., images/logo.png.

Example Code for Using Font Files:

from PIL import ImageFont
font_path = "assets/fonts/Monan.ttf"
font = ImageFont.truetype(font_path, 36)

tests/: Test Files

Contains test code and test data:

• Test data: e.g., test_namelist.csv.
• Test code: e.g., test_main.py.

logs/: Log Files

Stores logs generated during program execution, useful for tracking issues or recording critical information.

3. Common Questions

Q1: Can main.py be placed in the root directory?

Yes, but it’s recommended to place it under src/ to keep the root directory clean. If you need to simplify user operations, you can add a lightweight entry file in the root directory that calls src/main.py.

Q2: Where should font files be stored?

Font files should be stored in assets/fonts/ for easy management and access.

Q3: Where should temporary output files be stored?

Temporary files should be stored in output/ or output/tmp/ and cleaned up when no longer needed.

4. Complete Project Example

A well-designed project should have a clear directory structure to facilitate team collaboration and user interaction:

project/
  ├── src/                  # Main source code
  │    ├── main.py          # Main entry point
  │    ├── utils.py         # Utility module
  │    └── modules/         # Submodules
  ├── data/                 # Static data files
  │    ├── namelist.csv     # Name list file
  │    └── sample_data.json
  ├── output/               # Output files
  ├── config/               # Configuration files
  ├── assets/               # Static resources
  ├── tests/                # Test files
  ├── logs/                 # Log files
  ├── README.md             # Project description
  └── requirements.txt      # Dependency list

This structure ensures cleanliness and supports project scalability.