Project planning and code organization

What we're doing today

By the end of this session, you will have stopped writing code the way most beginners do — opening a blank file and typing furiously until something works — and started writing it the way working programmers actually do. You will plan a small project on paper first, then build the first tiny piece of it, run it, and add the next.

The temptation, every time, is to skip the planning and just start typing. I have done it. You will do it. And then you sit there at midnight with two hundred lines that almost work, no idea which part is broken, and a feeling in your stomach that you should start over. Today we kill that feeling before it starts.

The trap of the blank file

Open Python. Open a new file. Stare at it. What now?

Most beginners answer that question by typing the first line that pops into their head and hoping the rest will follow. Sometimes it does. Usually it does not. You end up with code that asks the user for input in three different places, prints things in four different styles, and has a for loop nested inside another for loop that even you cannot read by the end of the afternoon.

The fix is annoyingly old-fashioned. Before you type a single line of Python, write down — in plain English, on paper or in a notes app — what your program is going to do. Not in code. In sentences. Like you were explaining it to a friend who has never seen a computer.

There is a phrase chefs use: mise en place. It means "everything in its place." Before a serious cook turns on the stove, every onion is chopped, every spice is measured, every pan is within arm's reach. The cooking takes ten minutes because all the thinking happened first. Writing code is the same. The typing is fast. The thinking is slow. Most beginners reverse those two and wonder why nothing works.

Writing the steps in plain English first

Say you want to build a small budget tracker — a program that asks what you spent today, saves it, and shows you a running total. Before any Python, the plan looks like this:

1. Greet the user.
2. Ask what they spent today and on what.
3. Save it somewhere so it's there tomorrow.
4. Show the running total for the month.
5. Say goodbye.

That is five sentences. Anybody who can read English understands it. There is no Python in there yet, and that is the point. If you cannot describe your program in plain sentences, you do not understand your program well enough to write it.

This is the same trick you use for an essay. You don't sit down and write the first sentence of a five-page essay and hope a thesis appears by page three. You write the outline first — the points you want to make, in order — and then you fill in the paragraphs. Code works the same way. The numbered list above is the outline. Each step will probably become a function later.

The smallest version that works

Once you have your outline, do not build all five steps. Build the first one. Run it. Make sure it works. Then build the second one. Run that. Make sure it still works. Then the third.

If I sat down to build that budget tracker, my first version would do exactly one thing: ask the user what they spent and print it back. That's it. No saving, no totals, no nothing.

amount = float(input("How much did you spend today? "))
print("You spent:", amount)

Two lines. I run it. It works. Now I add the next piece — what was the spending on?

amount = float(input("How much did you spend today? "))
category = input("What was it for? ")
print("You spent", amount, "on", category)

Run it again. Still works. Now I think about saving it to a file. And so on. Each step is small enough that if it breaks, I know exactly which three lines broke it — the three lines I just added.

This is the opposite of how beginners usually work. Beginners write all five steps at once, run it, see ten errors, and have no idea which step caused which error. Build small. Run often.

Think of it like building a stool versus building a house. A stool is three legs and a seat. You build it in an afternoon, you sit on it, it either holds you or it does not. A house has plumbing and wiring and a roof and a foundation, and if you try to build all of those at once you will end up with a pile of bricks and no idea where the bathroom goes. Your first project is a stool. Build the stool.

One file is fine, until it isn't

For your first few projects, one file is plenty. Put everything in main.py — that is just the name people use for the one file you run. A 50-line file in one place is easier to read than 50 lines spread across four files.

Two signs it is time to split:

The file is over about 150 lines and you find yourself scrolling to remember what's in it.
The file is doing more than one kind of job — reading something, and analysing it, and printing it, all jammed together.

When you do split, the rule is one job per file. For that budget tracker, once it grew up a bit, the files might look like:

budget-tracker/
├── main.py          # the one you run
├── storage.py       # saves and loads from a file
└── display.py       # printing the summary nicely

Three files. Each one has a clear job. main.py is the main script — that is just programmer-speak for "the one file you actually run." The other two are modules. A module is a file of Python you can borrow from inside another file. That borrowing is called importing. It looks like this:

# in main.py
from storage import save_expense, load_expenses
from display import show_summary
 
expenses = load_expenses()
show_summary(expenses)

The line from storage import save_expense reads as: "from the file called storage.py, borrow the function called save_expense so I can use it here." That is it. No magic. You wrote storage.py yourself. Now main.py is using it like a little library that belongs to you.

For your first project, two or three files is plenty. Splitting for the sake of splitting is its own kind of mess.

Naming things

You will read your code more often than you write it. Future-you, opening this file in two months, deserves names that explain themselves.

A couple of habits I want you to pick up:

Functions usually do something, so name them with a verb: save_expense, load_contacts, calculate_total. If somebody reads the name out loud, it should sound like an action.
Variables usually hold something, so name them with a noun: expenses, total, user_name. They are containers, not actions.
Two or three words is fine. monthly_total beats mt every single time. Long and clear beats short and cryptic.

There's one test I use, and I want you to start using it. If you cannot name a function in a short, honest way, the function is probably doing too much. A function called do_stuff is not a function — it's a confession. A function called handle_user_and_save_and_print is two or three functions wearing a trenchcoat. Split it until each piece has a name that fits on its own.

This is also the test for whether your refactor is going well. A refactor is just programmer-speak for cleaning up code without changing what it does — same inputs, same outputs, tidier insides. If names get clearer after a refactor, you're going the right way. If they get vaguer, you're not.

Comments, used sparingly

You learned about comments in week one. The rule for project code is the same as it was then, just stricter: comments explain why, not what. The code already shows what.

# Add a 10% buffer because I always forget small cash spending.
total = base_total * 1.10

That comment tells the reader something they could not figure out from the code alone. Compare with this:

# Multiply by 1.10
total = base_total * 1.10

The second one is noise. The line itself already says that. Save your comments for the bits a stranger could not guess.

Your exercise

Pick one of these two small projects. Do not pick both. Do not invent a third.

A budget tracker that asks what you spent today, what it was for, and saves each entry to a file. When you run it again tomorrow, it remembers yesterday's entries.
A contacts CLI — short for "command-line interface," meaning a program you talk to by typing, not by clicking. It lets you add a contact (name, phone, email), list everyone you've saved, and find a contact by name.

Before you open Python, do these three things:

Write the steps of your program in plain English. Number them. Aim for between four and seven steps.
Decide on the smallest honest version — the bit you'd build first that would already be useful even if you stopped there.
Write the names of the functions you think you'll need. Verbs. Two or three of them.

Then open Python and build only the first step. Run it. Then the second step. Run it. Keep going.

Common slip-ups

Planning the whole project, then writing the whole project, then running it. You will hit a wall of errors and not know where to start. Build one step at a time. Run after every step.
Splitting files too early. Three files for a 40-line program is showing off, not engineering. One file is fine. Split when it actually hurts to read.
Naming variables x, data, temp, thing. You will not remember what data was holding. You will remember what expenses_for_may was holding. Be kind to future-you.
Writing comments that just repeat the code. A comment that says the same thing as the line below it is wasted ink. Comments are for the why.
Refusing to delete code. When you build the next step, you might find your first step was wrong. Delete it and write it again. Code is cheap. Stubbornness is expensive.

That is the whole session. Pick your project, write the plan on paper, then build the first piece. Next week we put what you've built somewhere other people can see it.