> For the complete documentation index, see [llms.txt](https://engineering.umh.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://engineering.umh.app/engineering/development-process/how-to-build/coding-standards/code-quality/readability.md). # Readability How to write code, comments, PR descriptions and documentation that the next person can follow without the context you had while writing them. Owner: Jeremy The best documentation is no documentation. A product like Apple's or Linear's needs no manual, and good code needs no comment. But good code still needs a good commit history, so the reader can get to the context and understand the decisions that led to it. This page applies to everything we write: code, comments, commit messages, PR descriptions, tickets and documentation. It starts where [Abstractions](/engineering/development-process/how-to-build/coding-standards/code-quality/abstractions.md) ends: the structure is right, and now the code and the text have to read well. ## Rules * We make the code explain itself first, through its names, types and [structure](/engineering/development-process/how-to-build/coding-standards/code-quality/abstractions.md). A comment is the last resort, because good code needs no comment ([Code comments](/engineering/development-process/how-to-build/coding-standards/code-quality/code-comments.md)). * We give context where the reader looks for it. Anyone can follow it up from the commit to the PR, the ticket, the rollout ticket and the customer request. ## Working memory and cognitive load **A human has a limited context window.** Working memory holds about three to four items at once ([Cowan 2001](https://doi.org/10.1017/S0140525X01003922)). Each undefined term or skipped step takes one of those slots. The easier code or a PR description is to understand, the better a human can check it. **Research on cognitive load separates two kinds of effort** ([Leppink et al. 2013](https://doi.org/10.3758/s13428-013-0334-1)). One is the effort the content itself needs. The other is the effort a poor presentation adds, such as a term used before it is explained. Only the second kind is ours to remove. [Simplicity](/engineering/development-process/how-to-build/coding-standards/code-quality/simplicity.md) makes the same split for code. ## Make the code explain itself **One concept gets one name in the code, the docs and the tickets.** The Management Console calls it a bridge. The umh-core config file still calls the same thing `protocolConverter`. Every reader who meets both has to translate between them. Before you coin a new word, look for the one that UMH or the field already uses. **Explain a new word before you use it.** Every new word is one more thing the reader has to keep in mind. Do not introduce a word you use only once. A PR title "Fix action error" makes the reader guess which action. "Saving a bridge with an invalid config shows no error" tells them. **Consistency helps only when it is consistency with a pattern we want more of.** Our codebase also holds code we don't want to write anymore. LLMs often find such a pattern in our code and take it as the reason to write more of it. The Boy Scout rule applies instead: leave the code better than you found it. **The coding standards pages say which patterns we want.** Each page opens with where that part of the code is going. A review comment like "this is not maintainable" gives the author nothing to change. Pointing to the rule on [Error management](/engineering/development-process/how-to-build/coding-standards/architecture/error-management.md) that a persistent error is never retried gives them something to check. **Where we have no standard yet, find a reference point.** For Go, look at what the Go standard library does in the most similar situation. If it has nothing similar, look at mature Go projects such as Kubernetes, then at other languages. We follow people we look up to: Martin Kleppmann for data systems, the Go developers for Go, Apple and Linear for UX. Where no clear reference exists, the owner of that part of the code picks one and everyone follows it. **The code reads from top to bottom.** Handle a failure right after the call that caused it, and leave a function as soon as it has nothing left to do. [Go Code Review Comments](https://go.dev/wiki/CodeReviewComments#indent-error-flow) and [TypeScript](/engineering/development-process/how-to-build/coding-standards/languages/typescript.md#control-structures) show how in each language. ## Give context **Context goes where the reader looks for it.** * Someone wondering how a line got this way runs `git blame` and reads the commit. The history of a decision goes in the commit message. * A reviewer opens the PR first. Why this change exists goes in the PR description. * The ticket holds the original problem as it first reached us. * The rollout ticket holds the impact on the customer and links the customer requests behind it. * Someone reading one file sees only the code. A comment there holds only what the code itself cannot say. Each step links to the one above it. So anyone can follow the context up from the commit to the PR, the ticket, the rollout ticket and the customer request. [The pull request](/engineering/development-process/how-to-build.md#the-pull-request) and [The rollout ticket](/engineering/development-process/how-to-build/tickets/rollout.md) describe the format of those two. **Write for someone who was not there when you wrote it.** For a PR description, that is first the reviewer. But you and the reviewer are not the only people who will read it. Someone may look at it in a couple of years, without the review discussion and without you. If they can follow it, the reviewer can too. For a code comment, it is the next engineer who opens the file without the rest of the PR. Read your text as that person. What you do not understand yourself, a reviewer will probably also not understand. ## Try it on someone else **Before anyone reviews your work, try it on someone who has none of your context.** That can be a colleague or an LLM. * **Let them guess first.** Show only the name, the function signature or the title, and ask what they expect it to do. Where their guess differs from your design, the design is probably what needs to change. * **Let them play devil's advocate and try to rip it apart.** If you have a good reason for everything, fine. Some of those reasons you might put directly into the text. * **Explain it out loud.** Walk through it step by step, even to a rubber duck. Where you start to stumble, something is missing in the text or the code. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://engineering.umh.app/engineering/development-process/how-to-build/coding-standards/code-quality/readability.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.