In our current codebases, we’ve leaned on static type systems or naming conventions to document our functions. And that’s not a bad start, they give us the basics: what goes in, what comes out, and the general shape of things. But as our project grows and we rely more on AI-powered tools, I’ve been thinking about what those approaches don’t cover. They don’t tell us the why, the context, the edge cases, or the quirks. That’s where comment blocks, those structured, natural-language notes above our functions come in. They’re especially vital for making our codebase work seamlessly with large language models (LLMs). That said, not every function needs a doc block, and when you do write them, they don’t need to spell out the “what” behind the code. You and tools like LLMs can already read that from the code itself. Here’s why we should make them a habit.
When to Use Them (and When Not To)
Doc blocks are great, but they’re not mandatory for every piece of code. If a function’s name, parameters, and implementation are self-explanatory—like add($a, $b) that just returns $a + $b – adding a doc block is overkill. Modern IDEs, and even LLMs, can read that code and tell you exactly what it does without extra help. Save doc blocks for cases where the purpose or context isn’t obvious, think complex logic, edge cases, or business-specific rules. The goal is clarity, not clutter.
And when you do write them, don’t waste time repeating the “what.” The example above? It just echoes what the function name and code already say. You don’t need a doc block to tell you it calculates a total with tax—code and AI can figure that out. Instead, focus on the “why.” Why does this function exist? What’s the bigger picture? Here’s a better take:
/**
* Checks if a user has exceeded their daily login attempts.
* Caps are enforced per calendar day to prevent brute-force attacks.
*
* @param attempts - Number of login attempts so far
* @param maxAttempts - Maximum allowed attempts (default: 5)
* @returns True if the limit is exceeded, false otherwise
*/
function isLoginLimitExceeded(attempts: number, maxAttempts: number = 5): boolean {
return attempts > maxAttempts;
}The doc block for isLoginLimitExceeded is helpful because it goes beyond the simple code, attempts > maxAttempts to explain why the function exists: it enforces a security cap on daily login attempts to prevent brute-force attacks. This context, including the daily scope, isn’t obvious from the code alone, making the doc block valuable for understanding intent and avoiding misuse, all while staying concise and not repeating what the code already shows.
We’re not just writing code for ourselves anymore. Context is king.
Beyond AI: The Human Factor
Even setting LLMs aside, doc blocks make our lives easier. Types won’t tell you why we chose one approach over another, or what trade-offs we accepted. They won’t warn you about that one edge case which crashed production. Doc blocks do.
A Small Investment, A Big Payoff
The best bit is that it’s really cheap to do, especially since LLMs can handle most of the heavy lifting. Tools like Cursor can generate solid doc block drafts based on our code and a quick prompt, leaving us to just tweak or approve them. That tiny upfront effort pays off fast. Better comments mean better AI assistance, fewer misunderstandings, and a codebase that’s more maintainable for humans and machines alike. Let’s start adding them where it makes sense especially in complex or critical functions.
Leave a Reply