# 2 · Structure: shaped for the next reader Code is written once and read many times, mostly by someone who wasn't there when it was written. They have to understand it before they can change it. You write code in seconds; they read it in minutes, every time they come back. Shape it for them. Most of these rules have two failure directions. Agents tend to fall into both: too little structure in one file, too much invented structure in the next. --- ### S1 · Names say what a thing is, in the project's words **Rule:** Name things for what they are or do here: `unpaidInvoices`, not `data`; `sendReceipt`, not `handleProcess`. Use the word the codebase and the person already use for a concept: if they say "member", don't introduce "user". Functions are verbs, values are nouns, and booleans read as yes or no questions (`isPaid`, `hasAccess`). The wider a name is used, the more complete it should be: `i` in a three-line loop is fine, an export needs a full name. **Why:** Names are most of what the next developer reads. A good name saves them opening the function. A vague one means reading every line, and a new word for an old concept makes them wonder whether it's a different thing. **Agent trap:** generic names (`data`, `result`, `info`, `item`, `temp`, `handleData`, `processItems`, `Manager`, `Helper`, `utils2`). Or bringing your own vocabulary: the project says "workspace", your new code says "organisation", and now the codebase has both. **Check:** for each new name, find the same word used for the same thing elsewhere in the project. For each generic word in your diff (`data`, `info`, `handle`, `process`, `manager`), is there a more specific one? > **In ihumane Pro** (https://ihumane.ai/#pricing): > - S2 · One job per function > - S3 · Put code where the next person will look for it > - S4 · No abstraction until it's needed twice > - S5 · One shape per thing > - S6 · Handle an error where something can be done about it > - S7 · Check at the edges, trust the inside > - S8 · Name a value once; make it a setting only if it changes ## Summary checklist - [ ] Every new name uses the project's word for the concept; no `data`, `info`, `handle`, `manager`. - [ ] Every new function can be described in one sentence without "and". - [ ] New code sits where someone would look for it; no new folders or layers nobody asked for. - [ ] Every new abstraction, parameter and option has at least two real uses. - [ ] Each concept has one shape; each function returns one kind of thing. - [ ] Every `catch` recovers, adds context and rethrows, or reports at a boundary. - [ ] Input is checked where it enters, and not re-checked inside. - [ ] Meaningful values are named once; settings exist only for what really changes.