Anatomy of a file

imports, constants, definitions, entry point

What it is

Almost any code file is laid out the same way: at the top what it needs to work, in the middle the definitions, at the bottom the run. Knowing these four zones, you can find your way around an unfamiliar file in half a minute without reading it through.

The order is not accidental: it matches the order in which the code executes when the file is imported.

What it looks like in code

Here is a whole file — all four zones in order:

"""Reminder bot. The whole thing in one file."""
import os
import sqlite3

DB_PATH = os.environ.get("DB_PATH", "reminders.db")
MAX_TEXT = 200


def get_conn() -> sqlite3.Connection:
    conn = sqlite3.connect(DB_PATH)
    conn.row_factory = sqlite3.Row
    return conn


def add_reminder(user_id: int, text: str) -> int:
    if len(text) > MAX_TEXT:
        raise ValueError(f"text is longer than {MAX_TEXT} characters")
    with get_conn() as conn:
        cur = conn.execute(
            "INSERT INTO reminders (user_id, text) VALUES (?, ?)",
            (user_id, text),
        )
        return cur.lastrowid


def main() -> None:
    ...


if __name__ == "__main__":
    main()

What to read in each zone

Imports answer the question "what does this file depend on". import sqlite3 — it works with a database. See import requests and the file goes out to the network. This is the first thing worth reading: the imports tell you what the file is in the business of doing.

Constants are settings lifted to the top so they are easy to find. DB_PATH = os.environ.get("DB_PATH", "reminders.db") reads as: take the value from the environment variable, and if it isn't there, use reminders.db.

Definitions are the longest zone and the most harmless. The key point: def only describes a function, it does not run it. The file can be imported and not a single line inside a def will execute.

The entry point is the if __name__ == "__main__": line. It reads as: "if this file was run directly rather than imported, do what follows."

What to tell the AI

Break this file down by zones: what is in the imports, which
constants there are, which functions are defined and what runs
on startup. Briefly, one line per item.

For an unfamiliar project a different question is more useful:

Which function in this file should I start reading to
understand what it does? Don't explain the whole file,
just say where to start and why.

What to look for

Code outside functions. Anything written at the top level that is not an import, a constant or a definition will execute when the file is imported. The line conn = sqlite3.connect(DB_PATH) outside a function means the database opens simply because something imported the file — and that is almost always a mistake.

No entry point in a file meant to be run. If if __name__ == "__main__": is missing but the file is supposed to be runnable, somewhere near the bottom there will be a bare call — and it fires on import too.

Constants that aren't constant. A name in capitals promises the value does not change. If the AI wrote MAX_TEXT = 200 and then MAX_TEXT = get_limit() somewhere, it misleads everyone, including the next AI.

Secrets in constants. TOKEN = "123456:ABC-DEF" right there in the file means the token goes into git and stays in the history forever. The right way is an environment variable (article 5.7).

Cheat sheet