Writing for engineers

Commit messages

Picture a note taped inside a wall for whoever renovates next. A commit message is a note to the next person who runs git blame on this line, often you.

Retry webhook delivery on 5xx responses

Partners' endpoints sometimes return 503 during their deploys, and we
dropped those events. Retry up to 5 times with exponential backoff, and
send failures to the dead-letter queue so support can replay them.

Fixes #412

The conventions:

• A subject of about 50 characters, 72 at most, in the imperative mood, the form you'd use for a command: "Add", "Fix", "Retry", as if completing "This commit will...". No period. One that follows all of this: "Retry webhook delivery on 5xx responses".
• A blank line, then a body that explains why and any trade-offs. The diff already shows what.
• Wrap the body at 72 characters.
• Some teams use Conventional Commits prefixes, such as fix: and feat:, for automated changelogs.

"fix", "update" and "wip" tell nobody anything.

In plain words: the diff shows what changed. Your message says why.

def check_subject(subject):
    problems = []
    if len(subject) > 72:
        problems.append("over 72 characters")
    if subject.endswith("."):
        problems.append("ends with a period")
    if subject[:1].islower():
        problems.append("starts with a lowercase letter")
    if subject.lower() in {"fix", "update", "wip", "changes"}:
        problems.append("says nothing")
    return problems or "ok"

for s in ["Retry webhook delivery on 5xx responses", "fix", "updated the thing.",
          "Add retry logic to the webhook delivery client so failed events are not lost for partners"]:
    print(repr(s[:44]), check_subject(s))

Bug reports

A doctor can't do much with "it hurts". Where, since when, and what makes it worse? A good bug report gets fixed. It has:

• a specific title: "Checkout total ignores discount when cart has 10+ items";
• steps to reproduce, numbered, starting from a clean state;
• expected and actual results;
• the environment: version, browser or OS, account type;
• logs, screenshots, and a minimal reproduction if you can make one.

NEEDS = {"steps": ["steps", "1."], "expected": ["expected"], "actual": ["actual"], "version": ["version", "v1.", "v2."]}

def missing(report):
    text = report.lower()
    return [part for part, words in NEEDS.items() if not any(w in text for w in words)]

print(missing("Checkout is broken, please fix ASAP!"))
print(missing("""Total ignores discount with 10+ items (v2.4, Chrome)
Steps: 1. Add 10 items 2. Apply SAVE10
Expected: $90. Actual: $100."""))

Comments and docstrings

Code says what; comments should say why. A note on a recipe says "go easy on the salt, the stock is salty already", not "add salt". So write the reason for an odd choice, a link to the bug it works around, a warning. Docstrings describe a function's contract: what it takes, returns and raises.

def first_word(subject):
    if ":" in subject.split()[0]:
        subject = subject.split(":", 1)[1].strip()
    return subject.split()[0].lower()

for s in ["Added retries to webhooks", "fix: Handle empty carts", "Fixing the tests", "Bring back dark mode"]:
    w = first_word(s)
    print(f"{w:10}", "looks past/continuous" if w.endswith(("ed", "ing")) else "fine")

subject = "Fix: retry webhook delivery on 5xx responses."
print(len(subject) <= 50, subject.endswith("."))

Don't repeat the diff

A commit message saying "changed timeout from 30 to 60" tells the reader nothing the diff doesn't. Someone finding this line in two years wants to know why. "Partner API takes up to 45 s at peak, so 30 s caused failed syncs" answers that. It also tells them when the change can safely be undone: when that partner gets faster.

Lead with the conclusion

Most technical writers build up to their point, the way we were taught in school: background, then analysis, then conclusion. Busy readers stop partway, so they miss the only part they needed. Turn it around, the way a news story does. Start with what you want or what you found. Then give the reasoning for whoever wants it.

For example, begin with "I recommend Postgres over DynamoDB, mainly because our queries need joins." The reader knows your answer straight away, and they can decide how much of the rest to read.

Why non-goals earn their place

Writing down what you're deliberately not doing feels like wasted space, and it may be the most useful part of a design doc. It stops people from asking "shouldn't this also handle X?" in every review, and it keeps the project from quietly growing. If a reviewer strongly disagrees with a non-goal, you've found that out before building anything, which is exactly when you want to.

Comments should explain why

A comment that says what the code does goes stale, and it adds nothing. # add 1 to retries above retries += 1 is only noise. Save comments for what the code can't say: "The vendor rejects batches over 500, even though their docs say 1,000."