Unit 08.04: A structure a second developer can navigate

The measure of a project structure is whether a new developer can find the file without asking.

Six questions, six predictable answers

What a new developer asks, and where the answer is.

The code lists them.

QUESTIONS = [
    ("where do I add an endpoint?",        "app/routers/<resource>.py"),
    ("where is the logic for X?",          "app/services/<resource>.py"),
    ("what does this endpoint accept?",    "app/models.py, or the /docs page"),
    ("where do I change the model vendor?", "app/clients/model.py"),
    ("where are the tests for X?",         "tests/ mirrors app/"),
    ("what configuration exists?",         "app/settings.py, one typed class"),
]
print(f"{'a new developer asks':38} answer")
for question, answer in QUESTIONS:
    print(f"{question:38} {answer}")

print("""
Every answer is a single predictable location. That is the whole measure of a
project structure -- not elegance, but whether someone who has never seen it
can find the file without asking.
""")

Every answer is a single predictable location. That is the whole criterion - not elegance, not minimal indirection, but whether the structure answers "where does this go?" the same way every time.

The test is cheap to run: hand the repository to someone who has not seen it, give them one of these questions, and watch whether they find the file or ask you.

The mistake this prevents

The mistake is optimising for the current author. A structure that makes sense to the person who grew it is the default outcome, and it is a different property from being navigable by someone who was not there.

Takeaway

Judge the structure by whether a newcomer finds the right file unaided. Every "where does X go?" should have one predictable answer.

Mark complete