There’s a specific kind of dread that comes with inheriting a codebase. You open a file, find a conditional that gatekeeps an entire payment flow, and the only comment above it is:
// edge case
if (charge.status === 'pending' Edge case what? From when? Written by whom?
This guide is about eliminating that feeling for the next developer and for the users reading your web content. Both are downstream of the same skill: writing with precise intent.
[ IMAGE ]
Where Most Teams Actually Get It Wrong
The two failure modes are opposite but equally useless.
Failure mode 1: Stating the obvious
// Loop through users
for (const user of users) {
sendWelcomeEmail(user);
}The code already says this. The comment adds zero information.
Failure mode 2: Saying nothing at all
const result = data.filter(d => d.flag !== 2 && !d.archived);What is flag: 2? A soft-deleted record? A compliance hold? A Stripe webhook artifact? Without context, every developer who touches this line is flying blind.
The fix isn’t to write more; it’s to write with purpose.
Example 1: Caching Layer – Comment on Why, Not What
Code already explains what it does. Comments should explain decisions the code can’t express. See the syntax-highlighted examples below:
Before:
// Cache the response
const cached = await redis.get(cacheKey);
if (cached) return JSON.parse(cached);
const data = await fetchFromDB(userId);
await redis.set(cacheKey, JSON.stringify(data), 'EX', 300);After:
// DB query for user profiles averages ~400ms under load.
// We cache for 5 minutes - acceptable staleness for non-billing data.
// Do NOT cache billing/subscription data here; see /services/billing.js
const cached = await redis.get(cacheKey);
if (cached) return JSON.parse(cached);
const data = await fetchFromDB(userId);
await redis.set(cacheKey, JSON.stringify(data), 'EX', 300);Now the next developer knows: this is intentional, the TTL is deliberate, and there’s an explicit guard against misuse. The original had none of that, just a comment restating what redis.get already implies.
Example 2: Stripe Webhook Handler – Document API Quirks Inline, Not in a Wiki
Third-party API behavior belongs next to the code that handles it. Wikis go stale. Inline comments don’t, or at least, they’re harder to miss during a PR review.
Before:
if (event.type !== 'payment_intent.succeeded') {
return res.status(200).send('ignored');
}After:
// Stripe sends `payment_intent.succeeded` AND `charge.succeeded` for
// the same transaction. We only process payment_intent events to avoid
// double-crediting the user's account.
// See: Stripe docs - "Handling duplicate events" (2024).
if (event.type !== 'payment_intent.succeeded') {
return res.status(200).send('ignored');
}Without that comment, a developer “cleaning up” the webhook handler might remove what looks like an arbitrary filter and ship a billing bug.
Example 3: Third-Party Geolocation API – Null Checks as Business Rules
Before:
const city = geoData.city ?? geoData.country ?? 'unknown';After:
// MaxMind returns `null` for city on Tor exit nodes and some VPN IPs.
// Fallback to country-level targeting. Do NOT throw here, this is
// expected for ~8% of requests based on our traffic profile.
const city = geoData.city ?? geoData.country ?? 'unknown';This turns a confusing null-check into a self-documenting business rule. The original did not indicate whether the null was a bug, an edge case, or intentional product behavior. It’s all three things at once, and only the comment makes that clear.
Example 4: React Focus Management – Guard Rails That Teach
Commenting isn’t just for backend logic. Frontend code has the same problem, especially around UI state, accessibility, and browser quirks.
Before:
useEffect(() => {
if (!ref.current) return;
ref.current.focus();
}, [isOpen]);
After:
// Shift focus into the modal when it opens so screen readers
// announce the dialog. Without this, focus stays on the trigger button
// and keyboard users can’t navigate modal content.
// See WCAG 2.1 criterion 2.4.3 (Focus Order).
useEffect(() => {
if (!ref.current) return;
ref.current.focus();
}, [isOpen]);
Now this is educational: a junior dev learns something, an accessibility auditor can verify intent, and the PR reviewer doesn’t have to ask “why?”
Protecting Production: When Comments Are Guard Rails
Some code paths must not be changed without understanding a hard constraint. Say so explicitly and give whoever eventually changes it a clear condition for doing so safely.
/**
* IMPORTANT: Do not remove the 150ms delay below.
*
* The legacy iOS app (v3.x, still ~12% of active users as of Q1 2025)
* sends a second POST if it doesn't receive a response within 200ms.
* The delay forces our de-duplication middleware to catch the retry.
* Removing it caused incident INC-2847 (double-charges, Jan 2025).
* Safe to remove when iOS v3 drops below 1% - track in analytics dashboard.
*/
await delay(150);
await processOrder(order);This comment prevents a regression. It also gives a future developer permission to clean it up with a clear, measurable condition attached.
7 Actionable Tips for Better Comments and Web Copy
Apply these across both your codebase and your web content:
- Comment on non-obvious decisions, not obvious mechanics. If the code clearly shows what’s happening, skip the comment. Only add one when the reason isn’t self-evident.
- Reference the source of truth for external constraints. Link to the third-party docs, the incident report, or the spec. // See Stripe docs: “Handling duplicate events” is worth more than a paragraph of paraphrasing.
- Date-stamp temporary workarounds. // Temporary: remove after migration to Postgres v16 (target: Q3 2025) permits future developers to clean up, and context for when.
- Write web copy at the decision point, not the feature level. Instead of “Our API supports OAuth 2.0,” write “Connect your existing Google or GitHub account, no new password needed.” Users act on outcomes, not features.
- Use error messages as micro-documentation. “Payment failed. Check that your card isn’t expired and retry, or contact support if this persists.” is a complete user guide in one sentence. “Error 402” is not.
- Run content through a structure check before you publish. For web copy: Does the heading answer a question? Does the first sentence resolve the user’s concern? Does the CTA say what happens next? If any answer is no, revise before shipping.
- Treat comments like code, review them in PRs. Outdated comments are worse than no comments. Add “are the comments still accurate?” to your team’s review checklist. If you wouldn’t ship stale code, don’t ship stale documentation. For written content, running a quick pass with a grammar and syntax checker can help catch inconsistencies and keep your messaging clear before it goes live.
The Compounding Payoff
Good comments and clear web copy don’t feel impactful on day one. The payoff is compounding.
A one-line comment that prevents a billing regression saves hours of debugging, a customer support wave, and a postmortem. A pricing page that clarifies billing cycles upfront eliminates a category of support tickets entirely.
These aren’t writing tasks; they’re engineering decisions with measurable output.
The developers who internalize this tend to write better documentation, clearer error messages, and more useful PR descriptions. The skill transfers because the underlying discipline is the same: understand your reader, remove what doesn’t help them, and be precise about what does.
Conclusion
Code comments, web content, even the clarity you get there is not a soft skill; it’s a force multiplier on everything your team ships. Every comment left on a grey area is going to be a future bug report. All generic, nonresponsively designed product pages are lost conversions.
The rule: if someone who has never seen this codebase a day in their life could not tell word for word what is happening and why, without asking anybody
If yes, you’re done. If not, perhaps one more sentence is all it takes.