What if the most important part of a program is the part the computer ignores?
That sounds backwards, because programming is usually taught as a conversation with the machine. You write instructions, the machine follows them, and the result appears. But in real work, a program is also a conversation with the human being who will read it later, often under pressure, often when something has already broken. In that setting, two tiny things become surprisingly powerful: functions, which give structure to action, and comments, which give structure to understanding.
One does work. The other explains work. Together, they reveal a deeper truth about programming: good code is not only about making the computer do the right thing, but about making meaning survive over time.
This is why the question is bigger than syntax. The real tension is this: How do we write instructions that are simultaneously executable and understandable?
The Computer Needs Precision, Humans Need Context
A function is a named set of instructions that performs a task. It takes input, processes it, and returns output. That description sounds technical, but its real importance is cognitive. A function compresses an action into a name. Instead of rereading every step, you can trust the name to carry the idea.
That compression matters because the human mind cannot hold every detail at once. If you see a line like calculate_total(price, tax), you immediately get the shape of the operation without tracing every multiplication and addition. The code becomes legible at a higher level. The function is not just a machine tool, it is a mental handle.
Comments serve a different but equally important purpose. A comment is text in a program that the computer does not run, but the human can. That makes it sound secondary, yet comments often carry the parts of reasoning that code cannot easily express: why a strange workaround exists, what assumption is being made, which edge case matters, or what future reader should not forget.
Code tells the machine what to do. Comments tell the human why it is being done.
That distinction is essential, because confusion in software rarely comes from a lack of instructions. It comes from a lack of shared context. The machine needs exactness. The human needs intention.
A function without a clear name is like a drawer with no label. A comment without a clear purpose is like a label on the drawer that says, “Stuff.” Neither helps much. The art of programming is creating a system where each form of text does the job it is best suited for.
The Best Abstraction Is a Promise
The deepest connection between functions and comments is that both are forms of abstraction, but they operate at different levels.
A function abstracts behavior. It says, “Here is a task, and here is a reliable way to perform it.” Its name becomes a promise of what happens inside. When you call a function, you are relying on that promise without needing to inspect every instruction.
A comment abstracts reasoning. It says, “Here is the story behind this code, and here is the part that would otherwise be invisible.” The comment does not execute, but it stabilizes interpretation. It tells future readers not just what the code does, but what mental model they should use when reading it.
This leads to a useful framework:
Functions reduce action complexity.
Comments reduce interpretation complexity.
Together, they reduce the cost of change.
That last point is easy to miss. Most code is not written once and forgotten. It is edited, refactored, extended, debugged, and inherited. In that environment, the primary challenge is not computation, it is continuity. The more clearly a program communicates its structure and intent, the less fragile it becomes when time passes.
Consider a grocery calculator. A function named subtotal(items) tells you it combines item prices into a partial sum. A comment above a slightly unusual tax rule might explain that certain items are exempt. If the tax law changes six months later, the reader does not have to guess whether the exemption was intentional. The function handles the logic, and the comment preserves the rationale.
Without the function, the code may still work, but it feels like a pile of steps. Without the comment, the code may still run, but the reasoning may be lost. In both cases, maintenance becomes guesswork.
The Real Problem in Programming Is Forgetting
People often think programming skill is mostly about writing correct instructions. But correctness is only the beginning. The harder problem is that code is a memory system, and memory decays.
You forget why you chose a particular variable name. You forget why a function returns a specific value. You forget why a workaround was necessary. When that happens, even good code becomes hard to trust. The result is a strange kind of technical debt: not just messy code, but lost intention.
This is where comments become more than decoration. They are a defense against future amnesia. A good comment does not repeat what the code already says. It records what the code cannot say easily: constraints, motivations, or tradeoffs.
For example:
# The API limits requests to 100 per minute, so we batch them here.
process_batches(data)
That comment is valuable because the function name alone cannot tell you whether batching is a performance choice, a correctness requirement, or a temporary hack. The comment preserves the reason, which is often the first thing lost when code is revisited.
Now compare that with a useless comment:
# Add one to x
x = x + 1
This does not preserve knowledge. It merely echoes the obvious. In fact, it can make code worse by creating noise that future readers must ignore. A comment earns its place only when it gives access to meaning that would otherwise be missing.
So the question is not whether to comment more. It is whether the text you add increases understanding. In that sense, comments are like annotations in the margin of a book. They are useful only when they help the next reader navigate complexity, not when they restate the sentence already on the page.
Naming, Explaining, and Trusting the Reader
A strong function name and a strong comment both depend on the same hidden skill: respecting the reader's attention.
When you choose a function name like validate_email instead of check, you are not merely being precise. You are compressing an expectation into language the reader can trust. They know what level of detail to expect without opening the implementation. Good names are miniature interfaces between thought and action.
Comments do a similar thing, but at a different altitude. They prepare the reader for surprises.
Suppose a function contains an unusual step, like reversing a list before processing it. The code may be valid, but if the reversal is non-obvious, the reader will waste time asking the wrong question: “Is this a bug?” A brief comment such as,
# Reverse here because the newest item must be processed first
prevents that confusion. The comment does not replace the code. It tells you how to interpret it.
This suggests a broader principle: clarity is not the absence of complexity, it is the management of complexity.
Good code does not pretend the world is simple. It acknowledges that some things are best packaged as functions and some things are best explained in comments. It is not trying to make the computer impressed. It is trying to make the human less lost.
There is a deeper ethical dimension here as well. Writing readable code is a form of courtesy. It assumes that someone else will inherit your work, and that their time matters. This is why the best code feels generous. It does not force the reader to reconstruct your thought process from scratch. It leaves a trail.
The highest compliment a reader can give your code is not “clever.” It is “I understood it quickly.”
A Practical Model: Separate Doing from Explaining
If functions and comments are both forms of communication, then the best way to use them is to separate their roles cleanly.
Think of a program as having two layers:
The doing layer, where functions perform tasks.
The explaining layer, where comments preserve context.
This separation keeps each layer honest. Functions should not try to explain everything, because execution is their job. Comments should not try to perform logic, because they are invisible to the machine. When those boundaries blur, code becomes harder to read and easier to misuse.
A useful test is this: if a piece of information helps the computer make a decision, it belongs in the code. If it helps a human understand the decision, it belongs in a comment. If it helps both, ask which form is more durable.
Here is a simple example:
def compute_discount(price, member_status):
# Members get 15 percent off because loyalty members are billed monthly
if member_status:
return price * 0.85
return price
The function name handles the task. The comment explains the policy. If the business rule changes, the comment makes it easier to update the code correctly. If the code is revisited later, the reader sees not just what happens, but why.
This is also why documentation matters. A function’s documentation tells us its name, its inputs, and its outputs. That is not bureaucratic overhead. It is a contract. The better the contract, the easier it is for someone else to use the function correctly without peering inside every line.
In large systems, these contracts are what prevent chaos. In small scripts, they save time. In both cases, they turn private thought into shared understanding.
Key Takeaways
Use functions to package action. If a task has a clear purpose, give it a name that lets the reader grasp it instantly.
Use comments to preserve reasoning. Explain why something is done, especially when the code would otherwise look surprising.
Do not comment the obvious. If the code already says it plainly, a comment should add context, not duplication.
Treat code as a communication system. The goal is not only for the computer to execute the instructions, but for humans to understand them later.
Write for the future reader. Assume you will forget your own reasoning, and leave enough context that a later version of you can recover it quickly.
Conclusion: Good Code Is a Memory of Thought
The deepest insight is that programming is not just about controlling machines. It is about preserving thought in a form that can survive time, revision, and human limitation.
Functions give thought a reusable shape. Comments give thought a readable trace. One helps action travel. The other helps intention endure. Together, they turn a program from a set of commands into a durable record of reasoning.
That is why the smallest text in code can matter so much. The lines the computer ignores may be the lines that determine whether a future human understands the system at all.
In the end, the best code is not merely correct. It is rememberable.
The Hidden Architecture of Good Code: Why the Smallest Text Matters Most | Glasp
