Code is read far more often than it's written, by people (including future you) who don't have the context that was obvious while writing it. Naming and comments are the two lowest-cost, highest-leverage tools for closing that gap — used well, or wasted, depending on how they're used.
3 min read
Writing code that's easy to type quickly and writing code that's easy for someone else to understand later are frequently different goals, and this domain's first lesson already established why the second one matters more: the first lesson's opening lesson established that most engineering time goes into reading and maintaining code, not writing it fresh. Every naming and commenting decision is really a decision about how much work a future reader has to do to understand something you already understand right now.
A well-chosen name documents intent permanently, for free, exactly at the point where it matters, without needing to be kept in sync with a separate comment that can drift out of date:
# Poor: says nothing about what the value represents or its units
d = 86400
# Better: the name alone answers "what is this"
seconds_per_day = 86400# Poor: generic, tells the reader nothing beyond "some data"
def process(data):
...
# Better: specific about what's actually happening
def validate_and_normalize_email(email):
...A good name answers "what is this, and why does it exist" without needing the reader to trace through the surrounding logic first — genuinely one of the highest-value, lowest-cost habits available, since it costs nothing extra at runtime and pays off every single time the code is read afterward.
Well-named code should make what it does self-evident — a comment repeating that is pure noise that can drift out of sync with the code it describes over time:
# Noise — the code already says this
# increment the counter by one
counter += 1
# Worth writing — explains a non-obvious reason, not restated by the code
# Retrying up to 3 times specifically because the upstream API has a
# documented ~2% transient failure rate under normal load (see INCIDENT-114)
for attempt in range(3):
...The test worth applying before writing any comment: would removing it leave a future reader confused about something the code itself can't tell them? If yes, it's earning its place — a hidden constraint, a workaround for a specific bug, a business rule that isn't obvious from the code alone. If no, it's just restating what a reader could already see, and it's one more thing that can quietly become wrong the next time the code changes and the comment doesn't.
A codebase where every file follows a different naming convention forces constant re-learning as you move between files — worse for overall productivity than any single convention being slightly less than ideal. Following a team's existing style consistently, even when you'd have picked differently yourself, is usually the higher-value choice than introducing yet another convention alongside the ones already in use.
Function and file organization communicate intent just as much as names and comments do — a function that does five unrelated things forces a reader to hold all five in their head just to understand any one of them, while five small, well-named functions let a reader engage with exactly the one they actually care about right now. This is directly the payoff of the refactoring lesson's small extracted functions: each one becomes a self-documenting unit a reader can reason about independently.
While you're writing code, you have more context in your head about the problem than anyone reading it later ever will — including future you, after the details have faded. The practical habit this implies: whenever something feels obvious while writing it, that's often the exact moment a name or a short comment would help most, precisely because it won't feel obvious to whoever reads it next without that same context.
Check your understanding
A quick comprehension check — not tracked, not graded, just for you.
1. Why is a well-chosen name considered a particularly high-value form of documentation?
2. What test should be applied to decide whether a comment is actually worth writing?
3. Why does the lesson argue that consistency matters more than any single naming preference?
Software Engineering Fundamentals