Project Organization

2.5. Project Organization#

Well-organized project structure saves time, prevents errors, and makes collaboration easier. This section covers best practices and conventions used across the industry.

2.5.1. Common Project Structures#

2.5.1.1. Web Application (Node.js/Python)#

myapp/
├── README.md           # Project documentation
├── LICENSE             # License file
├── package.json        # Project metadata
├── .gitignore          # Git ignore patterns
├── venv/               # Python virtual environment (NOT tracked in Git)
├── src/                # Source code
│   ├── index.js
│   ├── routes.js
│   └── config.js
├── tests/              # Test files
│   ├── unit/
│   └── integration/
├── public/             # Static files (CSS, JS, images)
├── data/               # Data files (databases, fixtures)
└── docs/               # Project documentation

2.5.1.2. Python Data Science#

data_science_project/
├── README.md
├── requirements.txt     # Python dependencies
├── venv/               # Virtual environment (NOT tracked in Git)
├── data/
│   ├── raw/            # Original data (never modify)
│   ├── processed/      # Cleaned data
│   └── external/       # Third-party data
├── notebooks/          # Jupyter notebooks
├── src/
│   ├── data_prep.py
│   ├── analysis.py
│   └── visualization.py
├── models/             # Trained models
├── results/            # Analysis output
└── scripts/            # Standalone scripts

2.5.1.3. Systems/DevOps#

infrastructure/
├── README.md
├── ansible/            # Configuration management
│   ├── playbooks/
│   ├── roles/
│   └── inventory.ini
├── terraform/          # Infrastructure as Code
│   ├── main.tf
│   ├── variables.tf
│   └── outputs.tf
├── docker/             # Container configs
│   └── Dockerfile
├── scripts/            # Automation scripts
└── docs/               # Architecture docs

2.5.1.4. Monorepo (Multiple Projects)#

monorepo/
├── packages/
│   ├── api/            # Backend API
│   ├── web/            # Web frontend
│   ├── mobile/         # Mobile app
│   └── shared/         # Shared utilities
├── scripts/            # Shared scripts
├── docs/               # Overall documentation
├── package.json        # Root dependencies
└── workspace config    # Tools configuration

2.5.1.5. .gitignore#

What NOT to version control:

# Common ignore patterns
__pycache__/
*.pyc
node_modules/
.DS_Store
.env                   # Environment variables
dist/                  # Build outputs
venv/                  # Virtual environments
.vscode/               # Editor settings (personal)
*.log                  # Log files

2.5.1.5.1. Why Ignore These?#

  • venv/, node_modules/ — Installed dependencies are reproducible from requirements.txt or package.json. Committing them wastes space and causes conflicts. Team members regenerate them locally: pip install -r requirements.txt or npm install.

  • .env — Contains secrets (API keys, database passwords) that should never be in Git. Use .env.example instead with placeholder values for reference.

  • dist/, pycache/ — Build artifacts and compiled bytecode are generated during development. Always exclude them; they’re recreated when needed.

  • .vscode/, .DS_Store — Editor-specific and OS-specific files that shouldn’t be forced on teammates. Everyone has different editors/systems.

  • *.log — Log files are temporary and project-specific. They bloat the repository and shouldn’t be tracked.

Key principle: Only commit source code and configuration. Everything else is either generated, environment-specific, or secret.

2.5.2. Best Practices#

2.5.2.1. Use Clear, Descriptive Names#

# Good: Purpose is obvious
docs/
models/
utils/
config/

# Bad: Unclear what's inside
stuff/
misc/
temp/
foo/

2.5.2.2. Separate Concerns#

# Good: Data, code, tests are separate
project/
├── src/        # Source code
├── tests/      # Tests
├── data/       # Data files
└── docs/       # Documentation

# Bad: Everything mixed together
project/
├── file1.py
├── test1.py
├── file2.py
├── README.txt
├── data.csv

2.5.2.3. Use Consistent Naming#

# Python conventions
my_module.py       # Lowercase with underscores
MyClass            # CamelCase for classes
my_function()      # Lowercase with underscores

# JavaScript conventions
myModule.js        # CamelCase or kebab-case
MyClass            # PascalCase for classes
myFunction()       # CamelCase

# Directories
docs/              # Plural for collections
src/               # Short, standard names

2.5.2.4. Avoid Deep Nesting#

# Too deep (hard to navigate)
project/src/lib/utils/helpers/string/formatting/
└── trim.js

# Better (clear hierarchy, shallow depth)
project/src/utils/
├── string-formatting.js
└── index.js

2.5.2.5. Keep Projects Portable#

Files should work regardless of location:

# Bad: Hardcoded paths
config_file = "/Users/john/project/data/config.json"

# Good: Relative to current file
import os
config_file = os.path.join(
    os.path.dirname(__file__),
    "../data/config.json"
)

# Or use environment variables
config_file = os.getenv(
    "CONFIG_PATH",
    "data/config.json"
)
Contents