narrow

narrow — the house style

Applies to all files: source, documentation, tests, configs, mailbox messages. No file type is exempt; only unbreakable tokens are (below).

1. The rule, verbatim

Source lines <= ~50 columns (they fit his phone preview pane). 2-space indent. Deep nesting is a design smell — flatten or extract.

And its two companions, also verbatim:

Define every acronym at its definition site in a comment the first time it appears (RPN = Reverse Polish Notation, TTS = Text To Speech, DHT = Distributed Hash Table, DI = Dependency Injection, etc.).

Comments are rich and explanatory on purpose — he loves reading the code. Match that voice.

2. Interpreting "~50"

• Aim at 50. The ~ is a small grace, not a loophole: the working checker in this repo flags anything past 52:

  awk 'length > 52 {print FILENAME":"FNR}' *.js
  

• Unbreakable tokens are exempt: a long URL, a base58 program id, a JSON string value, a markdown table row. Put the token on its own line; keep the prose around it narrow.

• WHY 50: lines fit a phone preview pane. The code is read on a phone more often than on a monitor. If it wraps there, it's wrong here.

3. Wrapping patterns (examples)

Break after operators/commas, indent the continuation 2 spaces (or align into the call):

// BAD — 80 wide, unreadable on the phone
const e = { ...ev, _seq: seq, _at: ev._at || now(), _id: ev._id || nodeId + ':' + seq };

// GOOD — the same object, narrow
const e = {
  ...ev, _seq: seq,
  _at: ev._at || now(),
  _id: ev._id || nodeId + ':' + seq,
};

// GOOD — conditions split before operators
if (top.kind !== 'op') break;
if (tp > p || (tp === p && a === 'L'))
  out.push(st.pop());

// GOOD — rust chains break at the dot
ben.balance = ben
  .balance
  .checked_add(amount)
  .ok_or(LedgerError::Overflow)?;

Flatten instead of nesting: early-return, or extract a named helper. Three indent levels is the smell threshold.

// BAD — nesting as control flow
if (a.type === 'KEY') {
  if (k === 'C') {
    return [{ type: 'Cleared' }];
  } else { ... }
}

// GOOD — guards, one level
if (action.type !== 'KEY') return [];
if (k === 'C') return [{ type: 'Cleared' }];

4. Comments — where they go

File header banner (every source file): a framed block stating what the file IS, the philosophy it carries, and any diagram worth drawing. Pattern:

/* ==============================================
 * NAME — one-line role     (<=50 col house)
 * ----------------------------------------------
 * Several sentences of real explanation. Why
 * this exists, what doctrine it enforces, what
 * the reader must not break.
 * ============================================ */

Section rules split a file into named parts:

// -- the event tape -----------------------
// ---- instruction contexts -------------------

Block comments ABOVE the code they explain — a short paragraph before a function or a tricky region, never a novel inside it:

// fold one event, notify, return its effects.
// an event carries identity (_id) and origin
// (_origin = the node that first decided it) so
// sync can dedup and avoid echo loops.
function commit(ev) { ... }

Trailing comments only for tiny labels that fit the same line:

const log = [];         // append-only facts
const RATE: u64 = 100;  // tokens per cent

5. Comments — the voice

• Rich and explanatory on purpose. The comments teach; the reader is here for pleasure as much as reference. Explain WHY and the doctrine, not what the next line syntactically does.
• Define every acronym at first use, in a comment, at its definition site: PDA = Program Derived Address, SBF = Solana Bytecode Format.
• State invariants in CAPS where they matter: THE LOG IS NEVER REWRITTEN.
• It's fine — encouraged — for a comment to carry personality ("a browser is enemy territory for secrets"), as long as it's also precise.

6. Tests and docs too

• Test files open with the same banner, and it lists the numbered claims the file proves. Test names are sentences: ok('log keeps originals — never rewritten', ...).
• Markdown prose wraps at ~50 like everything else; long links/table rows are the exempt tokens. Headers small and frequent; tables for status, prose for reasoning.
• 2-space indent everywhere, including YAML, JSON (where formatting is ours to choose), and shell.