Files, Folders & Projects

Core path: 30 minutes

Why does project organization matter if Python can still run the file?

Because software has to survive longer than the five minutes when you remember where everything is.

A lot of people accidentally invent this system first:

Downloads/
├── project.py
├── project2.py
├── project-new.py
├── project-final.py
├── project-final2.py
├── project-final-REAL.py
└── project-final-REAL-FIXED.py

That is not version control.

That is panic with filenames.

Git arrives later. Today the target is simpler: understand that a project is a structured collection of files and directories, and that structure communicates meaning.

A filename carries more than a label

Look at:

hello.py

hello is the base name.

.py is the extension normally used for Python source files.

The extension helps humans and tools understand the file's expected format. It is a convention, not a magical security boundary. The actual contents still matter.

You will encounter several file types in this course:

You do not need to master all of those formats now.

Notice the bigger point: a software project is more than the .py file you happen to be editing.

Folders express relationships

Suppose your project contains:

score-tracker/
├── main.py
├── README.md
├── data/
│   └── scores.csv
└── tests/
    └── test_score_calculator.py

The folder names communicate something before you open a single file:

data/   → stored information used by the application
tests/  → code that verifies behavior

Compare that with:

score-tracker/
├── main.py
├── scores.csv
├── test_score_calculator.py
├── notes.md
├── other.py
└── random.txt

Both structures may technically run.

Only one starts helping the next person understand the project before they read the code.

Project structure is part of the interface for developers

When another developer opens your repository, the project tree is one of the first things they see.

It answers questions such as:

• Where does execution probably begin?
• Where is data stored?
• Where are tests?
• Is documentation present?
• Which files are likely generated or temporary?

Good organization reduces how much somebody has to guess.

That somebody might be you next Monday.

Names should reduce decoding work

Compare:

x.py
thing.py
other.py
stuff.py

with:

main.py
score_calculator.py
player_search.py
storage.py

The second group gives the reader useful clues about responsibility.

The same rule will show up again with:

• variables;
• functions;
• classes;
• modules;
• Git commits.

Names do not need to be long. They need to be useful.

Relative location changes what a path means

Imagine this structure:

week02-project/
├── main.py
└── experiments/
    └── hello.py

From the project root, this relative path identifies the nested file:

experiments/hello.py

From inside experiments/, the same file can be referred to simply as:

hello.py

The file did not move.

Your current location changed how the relative path is interpreted.

Lesson 3 makes that concrete in the terminal.

A project root is a useful anchor

Developers often think in terms of the project root: the top-level directory that contains the files for one project.

For example:

player-roster/
├── main.py
├── data/
├── tests/
├── README.md
└── .gitignore

If instructions say:

Run this from the project root.

that means your shell should be located at player-roster/, not inside data/, tests/, or some parent directory three levels above it.

That language will appear throughout the course, so I want it clear now.

Repair a project that technically works

You inherit:

my-python-stuff/
├── x.py             # starts the program
├── thing.py         # calculates scores
├── notes.txt        # project documentation
├── numbers.csv      # player scores
├── other.py         # helper functions
└── testthing.py     # tests score calculation

A possible redesign:

score-tracker/
├── main.py
├── score_calculator.py
├── helpers.py
├── data/
│   └── scores.csv
├── tests/
│   └── test_score_calculator.py
└── README.md

Do not copy that structure just because it is shown here.

Explain each decision:

• Why main.py?
• Why move scores into data/?
• Why separate tests?
• Why rename thing.py?
• Why use Markdown for the README?

There may be more than one reasonable organization. Your design should still communicate intent.

One thing not to do yet

Do not create fifteen folders because professional repositories look complicated on GitHub.

Structure should earn its place.

A beginner project with one file does not need an enterprise architecture diagram and twelve empty directories.

Start simple. Add boundaries when the project actually develops responsibilities that need separation.

Quick project audit

Open one project from Weeks 1–2 and answer:

project root:
entry file:
other source files:
data files:
documentation:
folders:
one filename that communicates purpose well:
one name you would improve:

If you cannot identify the project root, fix that before adding more code.