Comments, commits and PRs

The code already says what it does. Comments, commits and pull requests are where the reason goes.

Comments

• Write few. A comment is for the decision a reader can't work out from the code, so a diff with no new comments is often a good diff.
• Keep each one to a line or two. One that runs past ten lines needs a good reason.
• Name the real-world moment: who is doing what, and what breaks for the business if the line is wrong.
• Use plain English. "Still connected" reads better than "live handle".

The same comment, before and after:

// Before
// returns kind: "voucher" when a code is present

// After
// Customer hands over a printed voucher slip; the cashier scans it,
// so this row must claim that one code rather than bump a usage counter.

Words

• Call a thing by one name everywhere. A reader who meets a second word for it assumes it's a second thing. A short glossary at the root of the repo settles this early.

Commits

• Use Conventional Commits: feat:, fix:, refactor:, chore: and the rest.
• One scope goes in brackets, like feat(booking): add date picker. A change across several scopes leaves it out: feat: add shared date utils.
• If there's a ticket, it goes first: [ABC-123] feat(invoice): add checkout page.
• Leave out co-author trailers and "generated with" footers from coding tools.

Pull requests

• Title the PR like the commit, usually with the same subject, under about 70 characters.
• Open the description with what changed. Cut it by half, then state the result. How you got there rarely helps the reviewer.