AdelKS/simple-english

Simple English

Say the main thing in as few ordinary words as it takes, and stop. The reader opens the code for the details.

Be concise

• Lead with the point: what the thing does, and why when that isn't obvious.
• Leave out what the code or diff already shows: the files touched, the order of the steps, the edge cases the code handles.
• Use the compact phrase of the trade: "drop unused icons", not "drop the icons that nothing uses".
• Say a fact once.
• Cut words, not facts. Keep each step the reader needs to see the problem, and state the consequence: "that date can differ from the day CI makes the release", not "the heading is written before the release day".

Stay clear

Concise isn't cryptic.

• Write one idea per sentence, with a subject and a verb. No semicolons, riddles or slogans, such as "no release, no type".
• Put the subject first and name who acts: "C++ computes X", not "X is computed in C++".
• Use simple tenses, and the present tense for what is still true: "QML never re-evaluates bindings on it", not "never re-evaluated".
• Write a condition as If X, Y.
• Repeat the noun instead of "it", "they" or "those" when the noun is a clause back or when more than one noun could fit.
• Keep "which" and "whose" clauses short. If the clause has a long subject of its own, write a separate sentence: "Debian and Ubuntu Qt packages don't have it", not ", which Debian's and Ubuntu's Qt packages leave out".
• Say a negative plainly: "ignore values outside the range", not "take no value past the range". Don't negate through the object: "the edit didn't emit updated()", not "the edit emitted no updated()". Write "nor" only after "neither".

Sound native

The text must read like something an English-speaking developer wrote. If a phrase reads like a translation, rewrite it, even when the rewrite is a word longer.

• Use compound nouns, not chains of "of": "app settings", "the CSV file dialog", "Debian and Ubuntu Qt packages". Use a possessive only when no compound works, such as "the sheet's density", and never two in a row. Allow one "of" per phrase at most.
• Use the usual verb of the trade: "show", "report", "fix", "support", "handle", "check". Don't make code a person that tells, answers or carries. Keep "own" for ownership in the C++ sense.
• Use one word per concept: pick "check" or "verify", "settings" or "options", and keep it.
• Don't repeat the article in a list: "the frame and delete button".
• Write "must" for a requirement and "can" for a possibility. Avoid "should", "may" and "might".
• Write "for example", not "e.g.". Use American spelling.
• Delete these words: "leverage" and "utilize" (write "use"), "in order to" (write "to"), "prior to" (write "before"), "ensure", "simply", "just", "easily", "seamlessly", "robust", "powerful", "comprehensive", "functionality", "it is worth noting that", "with this change", "is designed to", "allows you to" (name the thing and its verb), "under the hood", "out of the box".

Before and after, from real commit subjects:

Before	After
keep the settings of the app out of documents	don't save app settings in documents
Graph: tell the reader when an export fails	Graph: report export errors
add CardButton, the icon button of the top row of an object	add CardButton, the icon button on an object's top row
Sampler: take no value of a discrete object past its range	Sampler: ignore discrete object values outside the range
stop a full release whose notes carry another day	check the date in the release notes before a full release
build on Ubuntu 26.04, with its packages of Qt	build on Ubuntu 26.04, with its Qt packages

By kind of text

Commit message

• Write the subject as a short imperative that makes sense without the diff: "limit document values to the settings panel bounds", not "keep the numbers of a document within the range of the panel".
• One commit does one thing. If the body needs a second topic, split the commit.
• Start the body with what the code does now, then a short why.
• Mark a fact beyond the subject with "also": "Both reads also skip unknown keys, because newer versions can add some."
• Drop background the reader knows. Don't retell the diff or defend the change.

Code comment

• Write none by default. Write one for a reason the code doesn't show, a hidden invariant, or a workaround.
• Say what the code does, what follows from it, and why, one short sentence each. Skip a part the code already shows.
• Name the API and use no metaphors. The imperative is fine: "skip identical writes: they still update the mtime".
• Write the comment you would give a colleague who asks "why is this here?". Name the concrete effect, such as "xmin stays on the left", not a summary such as "the bounds sit where they are".

Examples:

• Before: // a vertical list keeps its width a secret, so the style paints a stray handle
• After: // a vertical ListView leaves contentWidth at -1, which the style renders as a collapsed handle
• Before: # the runner's glib and libsystemd need its new glibc, so the AppImage uses the host's glib and libdbus. linuxdeploy still copies the libraries that only they need, so the list names those too
• After: # don't bundle glib, libdbus and their dependencies. The AppImage then loads the host's versions. The Ubuntu 26.04 versions need glibc 2.43, which older distros lack.

Documentation

• Describe what the code does today. Name the thing and what it's for, and point at the file with the details.
• Put three or more parallel items in a bullet list.
• Put style, module and identifier names in backticks: FluentWinUI3.
• Mark a fact about third-party software that can change with "currently" or the version: "Debian and Ubuntu Qt packages currently don't have it."

Error message: what happened, the cause if known, and what to do. No apology.

Tooltip: what the widget sets.

Instructions for an agent: one rule per sentence, the condition first.

Leave alone

Code, identifiers, commands, paths, quoted messages, product names, and the names of buttons, tabs, fields and menu entries.

Before you deliver

Read the text once as its reader. Delete each sentence that doesn't help that reader. Check that every sentence left reads right the first time and sounds like usual English.

If you explained the same thing in chat, compare the two. If the chat version is clearer, use it.