Naming and code clarity

Name the meaning and the unit; convert in one named place; comment what code cannot say.

Before you read: predict

A ticket site holds a seat while its buyer pays. The venue's settings screen labels the field "Seat hold (minutes)", and the venue typed 15. Checkout's code:

A buyer clicks Pay 40 seconds after the seat was held. Checkout takes the payment only while Date.now() < expiresAt.

What happens?

const venue = { holdDuration: 15 };   // as the settings screen saved itfunction holdExpiresAt(heldAt, duration) {  return heldAt + duration * 1000;}const heldAt = Date.now();             // the moment the seat is heldconst expiresAt = holdExpiresAt(heldAt, venue.holdDuration);

The 30-second version

Readers meet most names at a call site, without the body. So a name says what its value means and, for any time, size or amount of money, its unit: durationMin, timeoutMs, priceCents. A wrong unit then shows where it is used. Comments keep what code cannot say; the style guide and nearby code settle names before taste.

Name the meaning and the unit; convert in one named place; comment what code cannot say.

How it works

Step 1 of 11

A name is read where it is used, not beside its body. It should say fully what the thing is or does (Google's guide).

Analogy: A farmhouse cheesemaker's make sheet, read by the relief cheesemaker who covers her holiday

At the cheese dairy	In code
the old sheet says "rennet 20": she meant millilitres per 100 litres of milk, and the relief adds 20 ml to the whole 500-litre vat	a bare number read in another unit (step 2)
the new sheet's column reads "rennet (ml per 100 L)", and "cut 4500" in the "cut (min after rennet)" column looks wrong before anyone acts on it	the unit in the name (step 3)
a dosing chart by the vat turns litres of milk into millilitres of rennet	one named conversion (step 4)
the margin note "scald 2 °C lower in May: spring milk sets faster"	a comment keeping what the numbers cannot (step 7)
"stir the curd" written beside the stirring row	a comment repeating its line (step 8)
the dairy keeps its own column order and abbreviations when a new cheesemaker joins	house conventions (step 10)

Breaks down when: a cheesemaker can taste and smell a wrong set before the cheese is pressed; a program never notices a wrong unit by itself, only a test or a reader does.

Contrasting case: one cheesemaker making one cheese alone every day: her shorthand serves only her, until someone covers her holiday.

In real terms: give every time, size and amount its unit and its meaning in the name, convert in one named place, and keep comments for what the code cannot say.

Examples, run for real

4.1 ExamHall EXH-4410: minutes read as seconds

ExamHall stores exams.duration in minutes. The candidate app's countdown called remaining(startedAt, duration, now), which adds duration * 1000; ECON-201's 90-minute exam started at 09:00.

4.1 EXH-4410 remaining(startedAt, duration, now) · exams.duration 90 (minutes) · at 09:10:00 returns -510000; the candidate app reads ≤ 0 as over, and the result first reaches 0 at 09:01:30
4.1 MR !4710 remainingMs(startedAtMs, durationMin, nowMs) with minutesToMs · at 09:10:00 returns 4800000 ms = 80 min

Ten minutes in, the app ended a 90-minute exam (step 2). MR !4710 puts the units in the names and converts once (steps 3, 4).

4.2 One conversion, two callers

4.2 MR !4710 minutesToMs(90) = 5400000 · the candidate countdown shows 80 min left at 09:10:00 · the proctor console's "ends at" column shows 10:30 · the factor 60_000 is written 1 time

The countdown and the proctor console call the same minutesToMs, so they cannot disagree about the unit (step 4).

Try it

Answer first, then check. Nothing is saved.

Question 1 of 7

A ticket site's catalogue gives prices in euros (price: 25 is €25). Finance's fee sheet sets the booking fee at 150 cents a ticket, and marketing's poster gives students 10% off the ticket price. The checkout page's code:

What does the page show a student buying one €25 ticket?

const BOOKING_FEE = 150;          // finance teamconst STUDENT_DISCOUNT = 10;      // marketing teamfunction studentTotal(ticket) {  return ticket.price + BOOKING_FEE - STUDENT_DISCOUNT;}const shown = `€${studentTotal({ price: 25 }).toFixed(2)}`;

Question 2 of 7

An MR to a ticket site adds a grace period. Its description: "A buyer who pays up to 30 seconds after their seat hold ends keeps the seat." The venue's settings store the hold as holdMin. The MR's new lines:

Three reviewers each suggest one change.

Which change makes the code do what the description says?

const holdMs = venue.holdMin * 60_000;const graceSec = 30;const expiresAtMs = seat.heldAtMs + holdMs;if (nowMs > expiresAtMs + graceSec) releaseSeat(seat);

Question 3 of 7

An MR to a video app adds three comments:

Which comment should the reviewer leave as it is?

// Studios' licences end playback at 23:59 in the viewer's own time zone, not the server'sconst endsAt = licenceEnd(title, viewer.timeZone); // go through the segments and add up their lengthsfor (const s of segments) totalSec += s.lengthSec; // the preview is 30 seconds longconst PREVIEW_SEC = 30;

Question 4 of 7

A chat app lets people attach files. Its product spec says "attachments up to 5 MB", and the upload check is:

Someone attaches a 2 KB text file, a 3 MB photo and an 8 MB video (1 KB = 1,024 bytes, 1 MB = 1,024 KB).

Which files does the app accept?

const MAX_ATTACHMENT = 5;               // from the product specfunction accepts(file) {  return file.size <= MAX_ATTACHMENT;}

Question 5 of 7

In review you suggest renaming limit to maxTicketsPerOrder in a ticket site's checkout. The author replies that limit is clear enough. The team's style guide says nothing about the name, and the same file names its other limits maxSeatsPerRow and maxHoldsPerBuyer.

Write three to five sentences: what you do next, and when the name would stop being a matter of taste.

Your answer (optional, stays on this page)

Question 6 of 7

An MR to a payments ledger adds three comments:

Which comment should the reviewer ask the author to replace with clearer code?

// an IBAN: two capital letters, two digits, then 11 to 30 capital letters or digitsconst IBAN = /^[A-Z]{2}\d{2}[A-Z0-9]{11,30}$/; /** Returns the account's balance in cents on the given date, counting only settled entries. */export function balanceOn(accountId, date) { /* … */ } // the amount after the 2% card feeconst netCents = Math.round(grossCents * 0.98);

Question 7 of 7

A video service's thumbnail worker, running on Node 24, fetches a film's frames from the media store. When the store is busy it answers 503 with Retry-After: 30, which HTTP defines as 30 seconds. On a 503 the worker calls:

How long after the 503 does the worker fetch again?

function onBusy(res) {  const retryAfter = Number(res.headers.get('retry-after'));  setTimeout(fetchFrames, retryAfter);}

Go deeper

Pro tips

Put the unit in every time and money name (timeoutMs, priceCents); a unit bug then becomes a line that looks wrong in review. When: writing or reviewing any duration, timestamp, size or amount, or answering the row's typical question "What would you rename in this MR, and why does it matter?" (steps 2, 3). Verify:
```
tip v1 remaining(startedAt, duration, now) · 0 of 3 time names carry a unit · MR !4710 remainingMs(startedAtMs, durationMin, nowMs) · 3 of 3
```
Status: RAN.

Source

quote-check.mjs finds every passage of this section verbatim in the saved text. Valid as of 2026-10-15.

Google Engineering Practices, What to look for in a code review: https://google.github.io/eng-practices/review/reviewer/looking-for.html (google-looking-for.txt). The row's source. Quoted: "A good name is long enough to fully communicate what the item is or does, without being so long that it becomes hard to read." · "“Too complex” usually means “can’t be understood quickly by code readers.”" · "the style guide is the absolute authority: if something is required by the style guide, the CL should follow the guidelines." · "If no other rule applies, the author should maintain consistency with the existing code." · "If you want to improve some style point that isn’t in the style guide, prefix your comment with “Nit:” to let the developer know that it’s a nitpick that you think would improve the code but isn’t mandatory." Supports steps 1 and 6–11.

Steps 2–5 and every executed key rest on runs on Node 24, not on a page.

Read first: Single responsibility as one reason to change

Checked against the tools and docs as of 2026-10-15.

Predict first