{total}
; } ``` Written well: ```jsx [ba.jsx] import { useEffect, useState } from "react"; export function Theme() { const [theme, setTheme] = useState("light"); useEffect(() => { setTheme(localStorage.getItem("theme") ?? "light"); }, []); return{theme}
; } ``` --- # Functions with many parameters (8 or more) *Code longer than it needs to be*: one of the ways AI coding agents bloat software, from lessloc's [pattern catalog](https://lessloc.org/patterns/index.md). lessloc catches it as [`long-params`](https://lessloc.org/guide/reference.md#tier-2). ## What makes functions with many parameters (8 or more) a bad practice? The standards that call it a bad practice: [CWE-1064](https://cwe.mitre.org/data/definitions/1064.html) (ISO/IEC 5055 maintainability); Sonar S107; Clean Code F1 Too Many Arguments. ## What does lessloc do about functions with many parameters (8 or more)? lessloc catches it as [`long-params`](https://lessloc.org/guide/reference.md#tier-2). - `long-params` (tier 2): A new function with 8 or more parameters. ## Examples Caught as `long-params`: ```python [bc.py] def make_order(a, b, c, d, e, f, g, h): return a ``` Written well: ```python [bc.py] def make_order(spec): return spec ``` --- # Deep nesting *Code longer than it needs to be*: one of the ways AI coding agents bloat software, from lessloc's [pattern catalog](https://lessloc.org/patterns/index.md). lessloc catches it as [`deep-nesting`](https://lessloc.org/guide/reference.md#tier-2). ## What makes deep nesting a bad practice? The standards that call it a bad practice: [CWE-1124](https://cwe.mitre.org/data/definitions/1124.html) Excessively Deep Nesting; Sonar S134; Fowler: Replace Nested Conditional with Guard Clauses. ## What does lessloc do about deep nesting? lessloc catches it as [`deep-nesting`](https://lessloc.org/guide/reference.md#tier-2). - `deep-nesting` (tier 2): Statements nested 4 or more control levels deep. ## Examples Caught as `deep-nesting`: ```python [ab.py] def scan(rows): for r in rows: if r: for c in r: if c: print(c) ``` Written well: ```python [ab.py] def scan(rows): for r in rows: for c in r or []: if c: print(c) ``` --- # Long functions *Code longer than it needs to be*: one of the ways AI coding agents bloat software, from lessloc's [pattern catalog](https://lessloc.org/patterns/index.md). lessloc catches it as [`long-function`](https://lessloc.org/guide/reference.md#tier-2). ## What makes long functions a bad practice? The standards that call it a bad practice: Fowler: Long Function; Sonar S138; [CWE-1121](https://cwe.mitre.org/data/definitions/1121.html). ## What does lessloc do about long functions? lessloc catches it as [`long-function`](https://lessloc.org/guide/reference.md#tier-2). - `long-function` (tier 2): A function over 100 code lines, 20 or more of them written by the change. --- # If-chains on literal values *Code longer than it needs to be*: one of the ways AI coding agents bloat software, from lessloc's [pattern catalog](https://lessloc.org/patterns/index.md). lessloc catches it as [`if-chain`](https://lessloc.org/guide/reference.md#tier-2). ## What makes if-chains on literal values a bad practice? The standard that calls it a bad practice: Fowler: Repeated Switches. ## What does lessloc do about if-chains on literal values? lessloc catches it as [`if-chain`](https://lessloc.org/guide/reference.md#tier-2). - `if-chain` (tier 2): Three or more if-branches on literal values of one variable, where a lookup table would do. --- # A file that keeps growing *Code longer than it needs to be*: one of the ways AI coding agents bloat software, from lessloc's [pattern catalog](https://lessloc.org/patterns/index.md). lessloc catches it as [`swollen-file`](https://lessloc.org/guide/reference.md#tier-2). ## What makes a file that keeps growing a bad practice? The standard that calls it a bad practice: [CWE-1080](https://cwe.mitre.org/data/definitions/1080.html) Source Code File with Excessive Number of Lines of Code. ## What does lessloc do about a file that keeps growing? lessloc catches it as [`swollen-file`](https://lessloc.org/guide/reference.md#tier-2). - `swollen-file` (tier 2): A file that grew by 150 or more lines and now has over 800 code lines. --- # Reformatting lines the task did not change *Code longer than it needs to be*: one of the ways AI coding agents bloat software, from lessloc's [pattern catalog](https://lessloc.org/patterns/index.md). lessloc gives every session a rule against it and catches it as [`churn`](https://lessloc.org/guide/reference.md#tier-2). ## What makes reformatting lines the task did not change a bad practice? The standard that calls it a bad practice: Google engineering practices: small, focused changes. ## What does lessloc do about reformatting lines the task did not change? lessloc gives every session a rule against it and catches it as [`churn`](https://lessloc.org/guide/reference.md#tier-2). - `churn` (tier 2): Lines only reformatted (quotes, spacing, punctuation) that the task did not need to change. --- # Net growth past a budget *Code longer than it needs to be*: one of the ways AI coding agents bloat software, from lessloc's [pattern catalog](https://lessloc.org/patterns/index.md). lessloc catches it as [`net-growth`](https://lessloc.org/guide/reference.md#tier-4). ## What makes net growth past a budget a bad practice? The standard that calls it a bad practice: Lehman's law of increasing complexity. ## What does lessloc do about net growth past a budget? lessloc catches it as [`net-growth`](https://lessloc.org/guide/reference.md#tier-4). - `net-growth` (tier 4): The change adds more than `maxNetLines` net lines. --- # Golfed code: nested ternaries, comprehensions with several `for` clauses, lines over 160 characters *Code longer than it needs to be*: one of the ways AI coding agents bloat software, from lessloc's [pattern catalog](https://lessloc.org/patterns/index.md). lessloc catches it as [`clever`](https://lessloc.org/guide/reference.md#tier-2) and [`dense-lines`](https://lessloc.org/guide/reference.md#tier-3). ## What makes golfed code a bad practice? The standards that call it a bad practice: Google Python Style Guide: "Optimize for readability, not conciseness"; ESLint no-nested-ternary; Sonar S3358. ## What does lessloc do about golfed code? lessloc catches it as [`clever`](https://lessloc.org/guide/reference.md#tier-2) and [`dense-lines`](https://lessloc.org/guide/reference.md#tier-3). The counterweight to `simpler`, so shorter never means cryptic. - `clever` (tier 2): Golfed code: nested ternaries, nested conditional expressions, comprehensions with several `for` clauses. - `dense-lines` (tier 3): Code lines over 160 characters, long strings and URLs aside. ## Examples Caught as `clever`: ```ts [z.ts] export const label = (n: number) => (n < 0 ? "neg" : n === 0 ? "zero" : "pos"); ``` Written well: ```ts [z.ts] export function label(n: number) { if (n < 0) return "neg"; return n === 0 ? "zero" : "pos"; } ``` Caught as `clever`: ```python [aa.py] def flat(grid): return [c for row in grid for c in row if c] ``` Written well: ```python [aa.py] from itertools import chain def flat(grid): return [c for c in chain.from_iterable(grid) if c] ``` --- # Swallowed errors: `except: pass`, an empty catch, `catch (Exception e) { return null; }`, Go's `if err != nil { return nil }` *Errors and checks hidden*: one of the ways AI coding agents bloat software, from lessloc's [pattern catalog](https://lessloc.org/patterns/index.md). lessloc catches it as [`swallowed-error`](https://lessloc.org/guide/reference.md#tier-1). ## What makes swallowed errors a bad practice? The standards that call it a bad practice: [CWE-390](https://cwe.mitre.org/data/definitions/390.html) Detection of Error Condition Without Action; [CWE-1069](https://cwe.mitre.org/data/definitions/1069.html) Empty Exception Block; [CWE-396](https://cwe.mitre.org/data/definitions/396.html). ## What does lessloc do about swallowed errors? lessloc catches it as [`swallowed-error`](https://lessloc.org/guide/reference.md#tier-1). - `swallowed-error` (tier 1): An error caught and dropped, such as `except Exception: pass` or an empty catch. The agent hears about it right after the write. ## Examples Caught as `swallowed-error`: ```js [ac.js] export function read(f) { try { return f(); } catch (e) { // ignore } } ``` Written well: ```js [ac.js] export function read(f) { try { return f(); } catch (e) { if (e.code !== "ENOENT") throw e; } } ``` Caught as `swallowed-error`: ```go [ad.go] package ad func Load(get func() error) error { if err := get(); err != nil { return nil } return nil } func Save(put func() error) error { err := put() if err != nil { return nil } return nil } ``` Written well: ```go [ad.go] package ad func Save(put func() error) error { err := put() if err != nil { return err } return nil } ``` --- # Silenced checks: `@ts-ignore`, `any`, blanket `# type: ignore` or `# noqa`, `eslint-disable` without a rule, `#[allow(dead_code)]`, `//nolint` without a reason *Errors and checks hidden*: one of the ways AI coding agents bloat software, from lessloc's [pattern catalog](https://lessloc.org/patterns/index.md). lessloc catches it as [`suppression`](https://lessloc.org/guide/reference.md#tier-1). ## What makes silenced checks a bad practice? The standards that call it a bad practice: Clean Code G4 Overridden Safeties; typescript-eslint ban-ts-comment and no-explicit-any; eslint-comments no-unlimited-disable; ruff PGH003, PGH004; golangci-lint nolintlint. ## What does lessloc do about silenced checks? lessloc catches it as [`suppression`](https://lessloc.org/guide/reference.md#tier-1). - `suppression` (tier 1): A blanket suppression: `@ts-ignore`, `any`, `# type: ignore` or `# noqa` without a code, `eslint-disable` without a rule, `nolint` without a linter and a reason, `allow(dead_code)`. ## Examples Caught as `suppression`: ```ts [a.ts] export const n: number = JSON.parse("1"); // @ts-ignore export const m = n.foo; ``` Written well: ```ts [a.ts] export const n = 1; // @ts-expect-error: the vendored typings miss foo (upstream issue 12) export const m = n.foo; ``` Caught as `suppression`: ```js [b.js] /* eslint-disable */ export const x = 1; ``` Written well: ```js [b.js] // eslint-disable-next-line no-console -- the CLI prints console.log(1); ``` Caught as `suppression`: ```python [c.py] import os # noqa x = os.sep # type: ignore ``` Written well: ```python [c.py] import os # noqa: F401 re-exported for plugins x = os.sep # type: ignore[attr-defined] ``` Caught as `suppression`: ```rust [d.rs] #[allow(dead_code)] fn helper() -> u8 { 1 } ``` Written well: ```rust [d.rs] #[allow(clippy::too_many_arguments)] fn helper() -> u8 { 1 } ``` Caught as `suppression`: ```ts [ag.ts] export function parse(s: string) { const data: any = JSON.parse(s); return data.id as any; } ``` Written well: ```ts [ag.ts] export function parse(s: string): { id: string } { return JSON.parse(s) as { id: string }; } ``` --- # Checks, fallbacks and catches for cases that cannot happen *Errors and checks hidden*: one of the ways AI coding agents bloat software, from lessloc's [pattern catalog](https://lessloc.org/patterns/index.md). What lessloc does: [`defensive`](https://lessloc.org/guide/reference.md#tier-2) catches a null check of a value just created, a type re-checked inside private code and `?.` on a fresh object. ## What makes checks, fallbacks and catches for cases that cannot happen a bad practice? The standards that call it a bad practice: Meyer, "Applying Design by Contract" (IEEE Computer, 1992): "never in both… avoid redundant tests"; Ousterhout: Define Errors Out of Existence; Anthropic's prompting guide: "Don't add error handling, fallbacks, or validation for scenarios that can't happen". ## What does lessloc do about checks, fallbacks and catches for cases that cannot happen? [`defensive`](https://lessloc.org/guide/reference.md#tier-2) catches a null check of a value just created, a type re-checked inside private code and `?.` on a fresh object. - `defensive` (tier 2): A check for a case that cannot happen, such as testing a value just created for emptiness. ## Examples Caught as `defensive`: ```python [ce.py] def make(): user = User("ada") if user is None: raise ValueError("no user") return user ``` Written well: ```python [ce.py] def make(name): if not name: raise ValueError("name is required") return User(name) ``` Caught as `defensive`: ```ts [cf.ts] function label(id: string) { if (typeof id !== "string") throw new Error("id"); const parts = { id }; return parts?.id; } export const show = (id: string) => label(id); ``` Written well: ```ts [cf.ts] export function label(id: string) { if (typeof id !== "string") throw new Error("id must be a string"); return id; } ``` --- # Removing validation, error handling, logging or stated rules to shrink code *Errors and checks hidden*: one of the ways AI coding agents bloat software, from lessloc's [pattern catalog](https://lessloc.org/patterns/index.md). lessloc catches it as [`removed-safeguard`](https://lessloc.org/guide/reference.md#tier-1). ## What makes removing validation or error handling to shrink code a bad practice? The standard that calls it a bad practice: lessloc's own "Never cut" list. ## What does lessloc do about removing validation or error handling to shrink code? lessloc catches it as [`removed-safeguard`](https://lessloc.org/guide/reference.md#tier-1). - `removed-safeguard` (tier 1): Logging, error handling, validation, or a comment that states a security rule or contract was removed. --- # SQL built from values with f-strings, concatenation or template strings *Shortcuts that trade away safety*: one of the ways AI coding agents bloat software, from lessloc's [pattern catalog](https://lessloc.org/patterns/index.md). lessloc catches it as [`unsafe`](https://lessloc.org/guide/reference.md#tier-1): pass values as query parameters. ## What makes SQL built from values instead of query parameters a bad practice? The standards that call it a bad practice: [CWE-89](https://cwe.mitre.org/data/definitions/89.html) SQL Injection; OWASP Top 10 A03:2021 Injection. ## What does lessloc do about SQL built from values instead of query parameters? lessloc catches it as [`unsafe`](https://lessloc.org/guide/reference.md#tier-1): pass values as query parameters. - `unsafe` (tier 1): A shortcut that trades away safety: SQL built from values, HTML built or escaped by hand, `Math.random()` for secrets, a fast hash for passwords, certificate checks turned off, text run as code. ## Examples Caught as `unsafe`: ```python [cj.py] def find(db, name): return db.execute(f"SELECT * FROM users WHERE name = '{name}'") ``` Written well: ```python [cj.py] def find(db, name): return db.execute("SELECT * FROM users WHERE name = ?", (name,)) ``` --- # HTML built or escaped by hand: `innerHTML` from values, `.replace('<', '<')` *Shortcuts that trade away safety*: one of the ways AI coding agents bloat software, from lessloc's [pattern catalog](https://lessloc.org/patterns/index.md). lessloc catches it as [`unsafe`](https://lessloc.org/guide/reference.md#tier-1): use `textContent` or the framework's rendering. ## What makes HTML built or escaped by hand a bad practice? The standards that call it a bad practice: [CWE-79](https://cwe.mitre.org/data/definitions/79.html) Cross-site Scripting; [CWE-116](https://cwe.mitre.org/data/definitions/116.html) Improper Encoding or Escaping of Output. ## What does lessloc do about HTML built or escaped by hand? lessloc catches it as [`unsafe`](https://lessloc.org/guide/reference.md#tier-1): use `textContent` or the framework's rendering. - `unsafe` (tier 1): A shortcut that trades away safety: SQL built from values, HTML built or escaped by hand, `Math.random()` for secrets, a fast hash for passwords, certificate checks turned off, text run as code. ## Examples Caught as `unsafe`: ```js [ck.js] export function show(el, name) { el.innerHTML = `${name}`; } ``` Written well: ```js [ck.js] export function show(el, name) { el.textContent = name; } ``` --- # `Math.random()` or `random` for tokens, passwords and session ids *Shortcuts that trade away safety*: one of the ways AI coding agents bloat software, from lessloc's [pattern catalog](https://lessloc.org/patterns/index.md). lessloc catches it as [`unsafe`](https://lessloc.org/guide/reference.md#tier-1): `crypto.randomUUID()`, `getRandomValues()` or the `secrets` module. ## What makes Math.random() or random for tokens and passwords a bad practice? The standard that calls it a bad practice: [CWE-338](https://cwe.mitre.org/data/definitions/338.html) Use of Cryptographically Weak Pseudo-Random Number Generator. ## What does lessloc do about Math.random() or random for tokens and passwords? lessloc catches it as [`unsafe`](https://lessloc.org/guide/reference.md#tier-1): `crypto.randomUUID()`, `getRandomValues()` or the `secrets` module. - `unsafe` (tier 1): A shortcut that trades away safety: SQL built from values, HTML built or escaped by hand, `Math.random()` for secrets, a fast hash for passwords, certificate checks turned off, text run as code. ## Examples Caught as `unsafe`: ```js [cl.js] export const token = () => Math.random().toString(36).slice(2); ``` Written well: ```js [cl.js] export const token = () => crypto.randomUUID(); ``` --- # Fast hashes (MD5, SHA-1, SHA-256) for passwords *Shortcuts that trade away safety*: one of the ways AI coding agents bloat software, from lessloc's [pattern catalog](https://lessloc.org/patterns/index.md). lessloc catches it as [`unsafe`](https://lessloc.org/guide/reference.md#tier-1): bcrypt, scrypt or argon2. ## What makes fast hashes (MD5, SHA-1, SHA-256) for passwords a bad practice? The standard that calls it a bad practice: [CWE-916](https://cwe.mitre.org/data/definitions/916.html) Use of Password Hash With Insufficient Computational Effort. ## What does lessloc do about fast hashes (MD5, SHA-1, SHA-256) for passwords? lessloc catches it as [`unsafe`](https://lessloc.org/guide/reference.md#tier-1): bcrypt, scrypt or argon2. - `unsafe` (tier 1): A shortcut that trades away safety: SQL built from values, HTML built or escaped by hand, `Math.random()` for secrets, a fast hash for passwords, certificate checks turned off, text run as code. ## Examples Caught as `unsafe`: ```python [cm.py] import hashlib def store(password): return hashlib.sha256(password.encode()).hexdigest() ``` Written well: ```python [cm.py] import bcrypt def store(password): return bcrypt.hashpw(password.encode(), bcrypt.gensalt()) ``` --- # Certificate checks turned off: `verify=False`, `rejectUnauthorized: false`, `InsecureSkipVerify: true` *Shortcuts that trade away safety*: one of the ways AI coding agents bloat software, from lessloc's [pattern catalog](https://lessloc.org/patterns/index.md). lessloc catches it as [`unsafe`](https://lessloc.org/guide/reference.md#tier-1). ## What makes certificate checks turned off a bad practice? The standard that calls it a bad practice: [CWE-295](https://cwe.mitre.org/data/definitions/295.html) Improper Certificate Validation. ## What does lessloc do about certificate checks turned off? lessloc catches it as [`unsafe`](https://lessloc.org/guide/reference.md#tier-1). - `unsafe` (tier 1): A shortcut that trades away safety: SQL built from values, HTML built or escaped by hand, `Math.random()` for secrets, a fast hash for passwords, certificate checks turned off, text run as code. ## Examples Caught as `unsafe`: ```python [cn.py] import requests def get(u): return requests.get(u, verify=False) ``` Written well: ```python [cn.py] import requests def get(u): return requests.get(u, timeout=10) ``` --- # Running text as code: `eval`, `exec`, `new Function` *Shortcuts that trade away safety*: one of the ways AI coding agents bloat software, from lessloc's [pattern catalog](https://lessloc.org/patterns/index.md). lessloc catches it as [`unsafe`](https://lessloc.org/guide/reference.md#tier-1): parse the input instead. ## What makes running text as code (eval, exec, new Function) a bad practice? The standard that calls it a bad practice: [CWE-95](https://cwe.mitre.org/data/definitions/95.html) Eval Injection. ## What does lessloc do about running text as code (eval, exec, new Function)? lessloc catches it as [`unsafe`](https://lessloc.org/guide/reference.md#tier-1): parse the input instead. - `unsafe` (tier 1): A shortcut that trades away safety: SQL built from values, HTML built or escaped by hand, `Math.random()` for secrets, a fast hash for passwords, certificate checks turned off, text run as code. ## Examples Caught as `unsafe`: ```js [co.js] export const calc = expr => eval(expr); ``` Written well: ```js [co.js] export const calc = (a, b) => a + b; ``` --- # Another language's API: `null` or `===` in Python, `.strip()`, `None` or `len()` in JavaScript, `null` in Go *Calls and packages that do not exist*: one of the ways AI coding agents bloat software, from lessloc's [pattern catalog](https://lessloc.org/patterns/index.md). lessloc catches it as [`made-up-api`](https://lessloc.org/guide/reference.md#tier-1). ## What makes another language's API a bad practice? The standard that calls it a bad practice: Sonar's quality profile for agent-written code targets "hallucinated APIs"; a call that does not exist fails the first time it runs. ## What does lessloc do about another language's API? lessloc catches it as [`made-up-api`](https://lessloc.org/guide/reference.md#tier-1). - `made-up-api` (tier 1): Another language's API, such as `null` in Python, `len()` in JavaScript or `None` in Go, or an import that no manifest declares and the platform does not provide. ## Examples Caught as `made-up-api`: ```python [cp.py] def first(xs): if len(xs) === 0: return null return xs[0] ``` Written well: ```python [cp.py] def first(xs): return xs[0] if xs else None ``` Caught as `made-up-api`: ```python [tests/test_cr.py] def test_load(): doc = load("[a]\nb = 1\n") assert doc["a"] != null ``` Written well: ```python [tests/test_cr.py] def test_load(): doc = load("""\ [a] smooth = true """) assert doc["a"]["smooth"] is True ``` Caught as `made-up-api`: ```js [cq.js] export const clean = s => s.strip(); ``` Written well: ```js [cq.js] export const clean = s => s.trim(); ``` --- # Imports of packages no manifest declares: a made-up name, or one never installed *Calls and packages that do not exist*: one of the ways AI coding agents bloat software, from lessloc's [pattern catalog](https://lessloc.org/patterns/index.md). lessloc catches it as [`made-up-api`](https://lessloc.org/guide/reference.md#tier-1): checked against every package.json, Python manifest, the standard library and the project's own modules. ## What makes imports of packages no manifest declares a bad practice? The standards that call it a bad practice: Spracklen et al., USENIX Security 2025 (5.2–21.7% of recommended packages do not exist); OWASP Top 10 A03:2025 Software Supply Chain Failures. ## What does lessloc do about imports of packages no manifest declares? lessloc catches it as [`made-up-api`](https://lessloc.org/guide/reference.md#tier-1): checked against every package.json, Python manifest, the standard library and the project's own modules. - `made-up-api` (tier 1): Another language's API, such as `null` in Python, `len()` in JavaScript or `None` in Go, or an import that no manifest declares and the platform does not provide. --- # Comments that narrate what the code does ("Loop through the users") *Comments and text*: one of the ways AI coding agents bloat software, from lessloc's [pattern catalog](https://lessloc.org/patterns/index.md). lessloc catches it as [`narration`](https://lessloc.org/guide/reference.md#tier-3). ## What makes comments that narrate what the code does a bad practice? The standards that call it a bad practice: Clean Code C3 Redundant Comment and Noise Comments; McConnell, *Code Complete* §32.4 (a comment that repeats the code is not acceptable in finished code); Ousterhout: Comment Repeats Code. ## What does lessloc do about comments that narrate what the code does? lessloc catches it as [`narration`](https://lessloc.org/guide/reference.md#tier-3). Comments that give a reason are kept. - `narration` (tier 3): Comments that narrate the code, decorate it or restate a name, closing-brace comments, and log lines that narrate each step. ## Examples Caught as `narration`: ```python [cg.py] def total(xs): # Loop through the items and add them up return sum(xs) ``` Written well: ```python [cg.py] def total(xs): # Refunds are negative, so the sum is already net return sum(xs) ``` --- # Banners, dividers, closing-brace comments, emoji decoration *Comments and text*: one of the ways AI coding agents bloat software, from lessloc's [pattern catalog](https://lessloc.org/patterns/index.md). lessloc catches it as [`narration`](https://lessloc.org/guide/reference.md#tier-3). ## What makes banners, dividers, closing-brace comments, emoji decoration a bad practice? The standard that calls it a bad practice: Clean Code: Position Markers, Closing Brace Comments. ## What does lessloc do about banners, dividers, closing-brace comments, emoji decoration? lessloc catches it as [`narration`](https://lessloc.org/guide/reference.md#tier-3). - `narration` (tier 3): Comments that narrate the code, decorate it or restate a name, closing-brace comments, and log lines that narrate each step. ## Examples Caught as `narration`: ```python [l.py] # ========== Helpers ========== def a(): return 1 ``` Written well: ```python [l.py] # Rates are cached for a minute: the provider bills per call def a(): return 1 ``` Caught as `narration`: ```js [m.js] function a() { return 1; } // end function ``` Written well: ```js [m.js] function a() { return 1; } ``` --- # Docs that restate the name (`"""Get the user."""`, `name: The name.`, `@returns The result.`) *Comments and text*: one of the ways AI coding agents bloat software, from lessloc's [pattern catalog](https://lessloc.org/patterns/index.md). lessloc catches it as [`narration`](https://lessloc.org/guide/reference.md#tier-3). ## What makes docs that restate the name a bad practice? The standards that call it a bad practice: Clean Code: Mandated Comments; Google Python Style Guide (no types in docstrings where annotations exist). ## What does lessloc do about docs that restate the name? lessloc catches it as [`narration`](https://lessloc.org/guide/reference.md#tier-3). - `narration` (tier 3): Comments that narrate the code, decorate it or restate a name, closing-brace comments, and log lines that narrate each step. ## Examples Caught as `narration`: ```python [n.py] def ship(order, carrier): """Ship an order. Args: order: The order. carrier: The carrier. """ return order ``` Written well: ```python [n.py] def ship(order, carrier): """Hand the order to the carrier; raises if the address is unverified. Args: carrier: one of "ups", "dhl"; anything else ships by post. """ return order ``` --- # History and messages to the requester ("Updated the parser to...", "As requested", "Generated by AI", dated change notes) *Comments and text*: one of the ways AI coding agents bloat software, from lessloc's [pattern catalog](https://lessloc.org/patterns/index.md). lessloc catches it as [`history`](https://lessloc.org/guide/reference.md#tier-3). ## What makes history and messages to the requester a bad practice? The standard that calls it a bad practice: Clean Code C1 and Journal Comments: history belongs in source control. ## What does lessloc do about history and messages to the requester? lessloc catches it as [`history`](https://lessloc.org/guide/reference.md#tier-3). - `history` (tier 3): Dates, change history or notes to the requester in comments. ## Examples Caught as `history`: ```js [o.js] // Updated the parser to handle empty input, as requested export const parse = s => s.trim(); ``` Written well: ```js [o.js] // Empty input is valid: forms post "" for untouched fields export const parse = s => s.trim(); ``` --- # Comment blocks and comment-heavy changes *Comments and text*: one of the ways AI coding agents bloat software, from lessloc's [pattern catalog](https://lessloc.org/patterns/index.md). lessloc catches it as [`comment-block`](https://lessloc.org/guide/reference.md#tier-3) and [`comment-density`](https://lessloc.org/guide/reference.md#tier-3). ## What makes comment blocks and comment-heavy changes a bad practice? The standard that calls it a bad practice: Clean Code: Too Much Information. ## What does lessloc do about comment blocks and comment-heavy changes? lessloc catches it as [`comment-block`](https://lessloc.org/guide/reference.md#tier-3) and [`comment-density`](https://lessloc.org/guide/reference.md#tier-3). - `comment-block` (tier 3): A comment block of 6 or more lines. - `comment-density` (tier 3): Comments make up more than `maxCommentRatio` of a file's added lines. --- # Log lines that narrate each step ("Starting...", "Successfully saved") *Comments and text*: one of the ways AI coding agents bloat software, from lessloc's [pattern catalog](https://lessloc.org/patterns/index.md). lessloc catches it as [`narration`](https://lessloc.org/guide/reference.md#tier-3) (three or more in a file). ## What makes log lines that narrate each step a bad practice? The standard that calls it a bad practice: Raymond, *The Art of Unix Programming*, Rule of Silence: "When a program has nothing surprising to say, it should say nothing". ## What does lessloc do about log lines that narrate each step? lessloc catches it as [`narration`](https://lessloc.org/guide/reference.md#tier-3) (three or more in a file). - `narration` (tier 3): Comments that narrate the code, decorate it or restate a name, closing-brace comments, and log lines that narrate each step. ## Examples Caught as `narration`: ```js [bd.js] export async function sync(db) { console.log("Starting sync..."); const rows = await db.all(); console.log("Fetched rows"); await db.save(rows); console.log("Successfully saved"); } ``` Written well: ```js [bd.js] export async function sync(db) { const rows = await db.all(); await db.save(rows); console.log(`synced ${rows.length} rows`); } ``` --- # Docs that still name what a change removed *Comments and text*: one of the ways AI coding agents bloat software, from lessloc's [pattern catalog](https://lessloc.org/patterns/index.md). lessloc catches it as [`stale-doc`](https://lessloc.org/guide/reference.md#tier-3). ## What makes docs that still name what a change removed a bad practice? The standard that calls it a bad practice: [CWE-1116](https://cwe.mitre.org/data/definitions/1116.html) Inaccurate Source Code Comments. ## What does lessloc do about docs that still name what a change removed? lessloc catches it as [`stale-doc`](https://lessloc.org/guide/reference.md#tier-3). - `stale-doc` (tier 3): A doc that still names something the change removed or renamed. --- # Doc files nobody asked for, and READMEs that grow by 40 or more lines nobody asked for *Comments and text*: one of the ways AI coding agents bloat software, from lessloc's [pattern catalog](https://lessloc.org/patterns/index.md). lessloc catches it as [`unrequested-doc`](https://lessloc.org/guide/reference.md#tier-3). ## What makes doc files and README growth nobody asked for a bad practice? The standard that calls it a bad practice: YAGNI. ## What does lessloc do about doc files and README growth nobody asked for? lessloc catches it as [`unrequested-doc`](https://lessloc.org/guide/reference.md#tier-3). - `unrequested-doc` (tier 3): A doc file nobody asked for, or a doc that grew by 40 or more lines without a request for docs. --- # Docs deleted wholesale to shrink a change *Comments and text*: one of the ways AI coding agents bloat software, from lessloc's [pattern catalog](https://lessloc.org/patterns/index.md). lessloc catches it as [`doc-removed`](https://lessloc.org/guide/reference.md#tier-3). ## What makes docs deleted wholesale to shrink a change a bad practice? The standard that calls it a bad practice: lessloc's own "Never cut" list. ## What does lessloc do about docs deleted wholesale to shrink a change? lessloc catches it as [`doc-removed`](https://lessloc.org/guide/reference.md#tier-3). - `doc-removed` (tier 3): More than 20 lines of documentation removed. --- # Always-loaded instructions that grow, or that include a directory tour *Comments and text*: one of the ways AI coding agents bloat software, from lessloc's [pattern catalog](https://lessloc.org/patterns/index.md). lessloc catches it as [`long-instructions`](https://lessloc.org/guide/reference.md#tier-3). ## What makes always-loaded instructions that grow a bad practice? The standard that calls it a bad practice: [arXiv:2602.11988](https://arxiv.org/abs/2602.11988) (context files with overviews raised cost by more than 20% and did not help). ## What does lessloc do about always-loaded instructions that grow? lessloc catches it as [`long-instructions`](https://lessloc.org/guide/reference.md#tier-3). - `long-instructions` (tier 3): A directory tour in always-loaded instructions, or instruction files over `instructionBudget` tokens. --- # Commit messages that recap the diff file by file *Comments and text*: one of the ways AI coding agents bloat software, from lessloc's [pattern catalog](https://lessloc.org/patterns/index.md). What lessloc does: The commit hook warns when a message lists the files the diff shows. ## What makes commit messages that recap the diff file by file a bad practice? The standard that calls it a bad practice: DRY: the diff already lists every file. ## What does lessloc do about commit messages that recap the diff file by file? The commit hook warns when a message lists the files the diff shows. --- # Dockerfiles, compose files, CI workflows and deploy configs nobody asked for *Files and folders*: one of the ways AI coding agents bloat software, from lessloc's [pattern catalog](https://lessloc.org/patterns/index.md). lessloc catches it as [`unrequested-file`](https://lessloc.org/guide/reference.md#tier-2). ## What makes CI workflows and Dockerfiles nobody asked for a bad practice? The standards that call it a bad practice: YAGNI; Google engineering practices: "functionality that isn't presently needed". ## What does lessloc do about CI workflows and Dockerfiles nobody asked for? lessloc catches it as [`unrequested-file`](https://lessloc.org/guide/reference.md#tier-2). - `unrequested-file` (tier 2): A deployment, container or CI file nobody asked for. --- # Tiny one-function files; file-per-concern splits *Files and folders*: one of the ways AI coding agents bloat software, from lessloc's [pattern catalog](https://lessloc.org/patterns/index.md). lessloc catches it as [`tiny-file`](https://lessloc.org/guide/reference.md#tier-2) and [`new-files`](https://lessloc.org/guide/reference.md#tier-4). ## What makes tiny one-function files and file-per-concern splits a bad practice? The standard that calls it a bad practice: Ousterhout: Shallow Module. ## What does lessloc do about tiny one-function files and file-per-concern splits? lessloc catches it as [`tiny-file`](https://lessloc.org/guide/reference.md#tier-2) and [`new-files`](https://lessloc.org/guide/reference.md#tier-4). - `tiny-file` (tier 2): A new code file under 10 code lines. - `new-files` (tier 4): The change adds more than `maxNewFiles` new code files. --- # New folders for one or two files; layer trees for small apps *Files and folders*: one of the ways AI coding agents bloat software, from lessloc's [pattern catalog](https://lessloc.org/patterns/index.md). lessloc catches it as [`new-folder`](https://lessloc.org/guide/reference.md#tier-2). ## What makes new folders for one or two files and layer trees for small apps a bad practice? The standards that call it a bad practice: Ousterhout: shallow modules; Martin's Common Closure Principle. ## What does lessloc do about new folders for one or two files and layer trees for small apps? lessloc catches it as [`new-folder`](https://lessloc.org/guide/reference.md#tier-2). Framework route folders (Next.js, SvelteKit, Expo) are exempt. - `new-folder` (tier 2): A new folder with one or two entries, or an examples or demo folder nobody asked for. --- # Junk-drawer `utils` and `helpers` modules and folders *Files and folders*: one of the ways AI coding agents bloat software, from lessloc's [pattern catalog](https://lessloc.org/patterns/index.md). lessloc catches it as [`junk-drawer`](https://lessloc.org/guide/reference.md#tier-2). ## What makes junk-drawer utils and helpers modules and folders a bad practice? The standard that calls it a bad practice: Fowler: Mysterious Name. ## What does lessloc do about junk-drawer utils and helpers modules and folders? lessloc catches it as [`junk-drawer`](https://lessloc.org/guide/reference.md#tier-2). - `junk-drawer` (tier 2): A new `utils`, `helpers`, `common`, `misc` or similar module or folder. --- # Vague names (`process_data`, `handle`) *Files and folders*: one of the ways AI coding agents bloat software, from lessloc's [pattern catalog](https://lessloc.org/patterns/index.md). lessloc catches it as [`vague-name`](https://lessloc.org/guide/reference.md#tier-2). ## What makes vague names (process\_data, handle) a bad practice? The standards that call it a bad practice: Fowler: Mysterious Name; Ousterhout: Vague Name. ## What does lessloc do about vague names (process\_data, handle)? lessloc catches it as [`vague-name`](https://lessloc.org/guide/reference.md#tier-2). - `vague-name` (tier 2): A new name made only of vague words, such as `process_data` or `handle`. --- # Moving or renaming files without a reason *Files and folders*: one of the ways AI coding agents bloat software, from lessloc's [pattern catalog](https://lessloc.org/patterns/index.md). lessloc catches it as [`moved-files`](https://lessloc.org/guide/reference.md#tier-2). ## What makes moving or renaming files without a reason a bad practice? The standard that calls it a bad practice: Google engineering practices: separate refactoring changes. ## What does lessloc do about moving or renaming files without a reason? lessloc catches it as [`moved-files`](https://lessloc.org/guide/reference.md#tier-2). - `moved-files` (tier 2): Files moved or renamed when the request did not ask for a refactor. --- # Secrets: a committed `.env`, API keys, private keys *Files and folders*: one of the ways AI coding agents bloat software, from lessloc's [pattern catalog](https://lessloc.org/patterns/index.md). lessloc catches it as [`secret`](https://lessloc.org/guide/reference.md#tier-0). ## What makes secrets (a committed .env, API keys, private keys) a bad practice? The standards that call it a bad practice: [CWE-798](https://cwe.mitre.org/data/definitions/798.html) Use of Hard-coded Credentials; [CWE-540](https://cwe.mitre.org/data/definitions/540.html). ## What does lessloc do about secrets (a committed .env, API keys, private keys)? lessloc catches it as [`secret`](https://lessloc.org/guide/reference.md#tier-0). - `secret` (tier 0): A credential in a known format in the added lines, or a new `.env` file that would be committed. ## Examples Caught as `secret`: ```js [k.js] export const stripe = "sk_live_51HxQz2eZvKYlo2C8a9Gm4Rt7Uv0Wx3Yz"; ``` Written well: ```js [k.js] export const stripe = process.env.STRIPE_KEY; ``` --- # Behavior added with no test changed in the same change *Tests and verification*: one of the ways AI coding agents bloat software, from lessloc's [pattern catalog](https://lessloc.org/patterns/index.md). lessloc gives every session the rule: new behavior gets one focused test. ## What makes behavior added with no test changed in the same change a bad practice? The standard that calls it a bad practice: Google engineering practices: tests ship with the change they test. ## What does lessloc do about behavior added with no test changed in the same change? lessloc gives every session the rule: new behavior gets one focused test. lessloc catches it as [`untested`](https://lessloc.org/guide/reference.md#tier-1). It is not raised for refactors, for fixes that do not grow the code, or for projects without tests. - `untested` (tier 1): The change adds behavior and no test changed, [with some exceptions](https://lessloc.org/guide/how-it-works.md#end-of-turn-unfinished-work-is-held-once). --- # Tests that assert nothing, or assert a constant *Tests and verification*: one of the ways AI coding agents bloat software, from lessloc's [pattern catalog](https://lessloc.org/patterns/index.md). lessloc catches it as [`empty-test`](https://lessloc.org/guide/reference.md#tier-1). ## What makes tests that assert nothing, or assert a constant a bad practice? The standard that calls it a bad practice: Carr, TDD anti-patterns: The Liar. ## What does lessloc do about tests that assert nothing, or assert a constant? lessloc catches it as [`empty-test`](https://lessloc.org/guide/reference.md#tier-1). - `empty-test` (tier 1): A test that asserts nothing or only a constant, or one that mocks the code it tests. ## Examples Caught as `empty-test`: ```python [tests/test_ae.py] def test_total(): total([1, 2]) def test_sum(): assert True ``` Written well: ```python [tests/test_ae.py] def test_total(): assert total([1, 2]) == 3 def test_import_runs(): import json ``` Caught as `empty-test`: ```python [tests/test_ag.py] def test_render(): expected = """\ [a] b = 1 """ render(expected) ``` Written well: ```python [tests/test_ag.py] def test_render(): expected = """\ [a] b = 1 """ assert render() == expected ``` Caught as `empty-test`: ```js [af.test.js] import { test } from "node:test"; test("adds", () => { add(1, 2); }); ``` Written well: ```js [af.test.js] import { test } from "node:test"; import assert from "node:assert"; test("adds", () => { assert.equal(add(1, 2), 3); }); ``` --- # Deleted, skipped, focused (`.only`), exited (`sys.exit(0)`) or force-passed tests *Tests and verification*: one of the ways AI coding agents bloat software, from lessloc's [pattern catalog](https://lessloc.org/patterns/index.md). lessloc catches it as [`weakened-tests`](https://lessloc.org/guide/reference.md#tier-0). ## What makes deleted, skipped or force-passed tests a bad practice? The standards that call it a bad practice: Clean Code T4 (an ignored test is a question); GitHub's AGENTS.md guidance: never remove a failing test. ## What does lessloc do about deleted, skipped or force-passed tests? lessloc catches it as [`weakened-tests`](https://lessloc.org/guide/reference.md#tier-0). Skips that depend on the environment are allowed. - `weakened-tests` (tier 0): Test assertions or tests removed, or tests newly skipped, focused or forced to pass. Tier 0 in a session; `check`, where a person may remove a test on purpose, reports it at tier 1. ## Examples Caught as `weakened-tests`: ```python [tests/test_aj.py] import pytest def test_pay(): pytest.skip("flaky") assert pay(2) == 2 ``` Written well: ```python [tests/test_aj.py] def test_pay(): assert pay(2) == 2 ``` --- # Test-only branches in production code; code shaped to pass a test *Tests and verification*: one of the ways AI coding agents bloat software, from lessloc's [pattern catalog](https://lessloc.org/patterns/index.md). lessloc catches it as [`test-logic`](https://lessloc.org/guide/reference.md#tier-1). ## What makes test-only branches in production code a bad practice? The standards that call it a bad practice: Meszaros: Test Logic in Production; Anthropic system cards: special-casing tests. ## What does lessloc do about test-only branches in production code? lessloc catches it as [`test-logic`](https://lessloc.org/guide/reference.md#tier-1). - `test-logic` (tier 1): Production code that checks whether tests are running, says it exists to make tests pass, or branches on a value that appears only in tests. ## Examples Caught as `test-logic`: ```python [j.py] import os def price(x): if "PYTEST_CURRENT_TEST" in os.environ: return 0 return x ``` Written well: ```python [j.py] import os def price(x): return x * float(os.environ.get("RATE", "1")) ``` Caught as `test-logic`: ```js [ah.js] export function price(x) { // special case for the test fixture if (x === 42) return 0; return x * 2; } ``` Written well: ```js [ah.js] export function price(x) { // Prices are stored in cents: 42 means $0.42 return x * 2; } ``` --- # Tests that mock the code they test *Tests and verification*: one of the ways AI coding agents bloat software, from lessloc's [pattern catalog](https://lessloc.org/patterns/index.md). lessloc catches it as [`empty-test`](https://lessloc.org/guide/reference.md#tier-1). ## What makes tests that mock the code they test a bad practice? The standard that calls it a bad practice: Carr, TDD anti-patterns: The Mockery. ## What does lessloc do about tests that mock the code they test? lessloc catches it as [`empty-test`](https://lessloc.org/guide/reference.md#tier-1). - `empty-test` (tier 1): A test that asserts nothing or only a constant, or one that mocks the code it tests. ## Examples Caught as `empty-test`: ```python [tests/test_cr.py] from unittest.mock import patch @patch("shop.pay.charge") def test_charge(mock_charge): mock_charge.return_value = 1 assert charge(5) == 1 ``` Written well: ```python [tests/test_cr.py] from unittest.mock import patch @patch("shop.pay.send_receipt") def test_charge(mock_send): assert charge(5) == 5 mock_send.assert_called_once() ``` Caught as `empty-test`: ```js [cart.test.js] import { test, vi } from "vitest"; import { total } from "./cart"; vi.mock("./cart"); test("total", () => { expect(total([1])).toBe(1); }); ``` Written well: ```js [cart.test.js] import { test, vi } from "vitest"; import { total } from "./cart"; vi.mock("./prices"); test("total", () => { expect(total([1])).toBe(1); }); ``` --- # Production code that branches on a value copied from the tests *Tests and verification*: one of the ways AI coding agents bloat software, from lessloc's [pattern catalog](https://lessloc.org/patterns/index.md). lessloc catches it as [`test-logic`](https://lessloc.org/guide/reference.md#tier-1). ## What makes production code that branches on a value from the tests a bad practice? The standards that call it a bad practice: Anthropic system cards: special-casing tests; Meszaros: Test Logic in Production. ## What does lessloc do about production code that branches on a value from the tests? lessloc catches it as [`test-logic`](https://lessloc.org/guide/reference.md#tier-1). - `test-logic` (tier 1): Production code that checks whether tests are running, says it exists to make tests pass, or branches on a value that appears only in tests. --- # Stopping short: a function, option or flag the request asked for is never written *Tests and verification*: one of the ways AI coding agents bloat software, from lessloc's [pattern catalog](https://lessloc.org/patterns/index.md). lessloc catches it as [`unaddressed`](https://lessloc.org/guide/reference.md#tier-1): names a request asks to exist ("add a `--status` flag", "implement `export_csv()`") are looked for in the final repository; one that appears nowhere holds the turn. ## What makes stopping short (a requested function never written) a bad practice? The standard that calls it a bad practice: ISO/IEC 25010 functional completeness. ## What does lessloc do about stopping short (a requested function never written)? lessloc catches it as [`unaddressed`](https://lessloc.org/guide/reference.md#tier-1): names a request asks to exist ("add a `--status` flag", "implement `export_csv()`") are looked for in the final repository; one that appears nowhere holds the turn. A name the request only mentions, a test or a private helper the agent names itself never counts, and names joined by "or" are alternatives. - `unaddressed` (tier 1): A function, option or flag the request asked for appears nowhere in the repository. A name the request only mentions does not count. --- # Stopping short: leaving part of the reported problem failing, and saying so *Tests and verification*: one of the ways AI coding agents bloat software, from lessloc's [pattern catalog](https://lessloc.org/patterns/index.md). lessloc catches it as [`unfinished`](https://lessloc.org/guide/reference.md#tier-1): in a turn that changed code, the agent's last reply is read sentence by sentence, with headings and lead-ins speaking for what is under them. ## What makes stopping short (part of the problem left failing) a bad practice? The standard that calls it a bad practice: ISO/IEC 25010 functional completeness. ## What does lessloc do about stopping short (part of the problem left failing)? lessloc catches it as [`unfinished`](https://lessloc.org/guide/reference.md#tier-1): in a turn that changed code, the agent's last reply is read sentence by sentence, with headings and lead-ins speaking for what is under them. An explicit marker that something is left broken ("Not fixed:", "Known limitation:") with a failure stated now, a neutral scope note ("Not changed:", "I left it alone") with a present-tense defect tied to the request (a name from its code, or the report's own example), the report's own example still failing, or the same problem suspected elsewhere and unchecked, holds the turn once, quoting the sentence. A fixed state, a cause, a condition, an offer, a tool's report or housekeeping never counts. - `unfinished` (tier 1): In a turn that changed code, the agent's last reply says part of the reported problem still fails, or that the same problem may be elsewhere, unchecked. --- # A refactor that changes existing tests *Tests and verification*: one of the ways AI coding agents bloat software, from lessloc's [pattern catalog](https://lessloc.org/patterns/index.md). lessloc catches it as [`refactor-tests`](https://lessloc.org/guide/reference.md#tier-2). ## What makes a refactor that changes existing tests a bad practice? The standard that calls it a bad practice: Fowler: refactoring preserves behavior. ## What does lessloc do about a refactor that changes existing tests? lessloc catches it as [`refactor-tests`](https://lessloc.org/guide/reference.md#tier-2). - `refactor-tests` (tier 2): A refactor changed existing tests.