@booklib/skills 1.2.0 → 1.3.0

package/clean-code-reviewer/references/practices-catalog.md

@@ -0,0 +1,282 @@
+# Clean Code — Practices Catalog
+
+Catalog of the most actionable principles from Robert C. Martin's
+*Clean Code: A Handbook of Agile Software Craftsmanship*, organized by category.
+Each entry includes the heuristic code, a short description, and the key test question.
+
+---
+
+## Naming
+
+### N1 — Choose Descriptive Names
+**Code:** N1  
+**Description:** A name should reveal its purpose so completely that the code reads like
+well-written prose. If a name requires a comment to explain it, it doesn't do its job.
+**Test question:** If someone reads only this name, do they know *why* this thing exists,
+*what* it does, and *how* it's used?
+
+### N2 — Names at the Appropriate Level of Abstraction
+**Code:** N2  
+**Description:** Names should match the abstraction level of the code they appear in.
+A `Modem` interface's `dial(phoneNumber)` reveals implementation; `connect(connectionLocator)`
+expresses the concept. Names at the right level can outlast implementation changes.
+**Test question:** Would this name still make sense if the underlying implementation changed?
+
+### N4 — Unambiguous Names
+**Code:** N4  
+**Description:** When two things in the same scope could be confused, names must be
+precise enough to remove ambiguity. `doRename()` is ambiguous; `renamePageAndOptionallyAllReferences()`
+is not. Verbosity in a name is cheaper than confusion in a reader.
+**Test question:** Could a reader confuse this name with anything else in the same context?
+
+### N5 — Long Names for Long Scopes
+**Code:** N5  
+**Description:** Single-letter variables are fine in a 3-line loop; in a 300-line function,
+they are inscrutable. The length of a name should correspond to the size of the scope
+it lives in. Long-lived names deserve investment.
+**Test question:** If this variable were referenced 50 lines from its declaration,
+would its name still be self-explanatory?
+
+### N7 — Names Should Describe Side Effects
+**Code:** N7  
+**Description:** If a function named `getOos()` creates an `ObjectOutputStream` when
+none exists, the name lies. Names must reflect everything the function does, including
+side effects. `createOrReturnOos()` is honest.
+**Test question:** Does this function's name describe *everything* it does, including
+any state it changes?
+
+---
+
+## Functions
+
+### Do One Thing (G30)
+**Code:** G30  
+**Description:** A function should do one thing, do it well, and do it only. The test:
+can you extract a meaningful sub-function from the body? If yes, the function is doing
+more than one thing. Functions that do one thing cannot be reasonably subdivided.
+**Test question:** Can you extract a meaningfully named sub-function from this function's body?
+
+### F1 — Too Many Arguments
+**Code:** F1  
+**Description:** The ideal number of function arguments is zero. One is fine. Two requires
+thought. Three requires strong justification. More than three is almost always wrong.
+When a function needs many related arguments, they usually form a concept that deserves
+its own class or struct.
+**Test question:** Could two or more arguments be wrapped into a meaningful object?
+
+### F3 — Flag Arguments Are Ugly
+**Code:** F3  
+**Description:** Passing a boolean to a function is a clear sign the function does two
+things — one for `true`, one for `false`. This violates "do one thing." The solution
+is always to split the function into two: one for each behavior.
+**Test question:** Does this function take a boolean that controls which of two paths it takes?
+
+### F2 — Output Arguments
+**Code:** F2  
+**Description:** Arguments are inputs. Readers naturally assume you pass things *in* to
+a function, not that a function writes results *back* through its parameters.
+`appendFooter(s)` is confusing; `report.appendFooter()` is not.
+**Test question:** Is the caller expected to read a result out of one of the arguments
+passed to this function?
+
+### G5 — Duplication
+**Code:** G5  
+**Description:** Duplication is the root of all evil in software. Duplicated code means
+two chances to make the same mistake, two places to change when the logic evolves,
+and two diverging truths. Every duplication should be addressed — usually by extraction,
+TEMPLATE METHOD, or STRATEGY.
+**Test question:** Does the same algorithm, condition, or business rule appear in more
+than one place?
+
+### G19 — Use Explanatory Variables
+**Code:** G19  
+**Description:** Complex calculations should be broken into named intermediate variables
+that explain each step. `(hourlyRate * hoursWorked) - taxRate` becomes three named
+variables that document the calculation's intent without a comment.
+**Test question:** Would a named intermediate variable replace the need for a comment
+explaining this expression?
+
+### G28 — Encapsulate Conditionals
+**Code:** G28  
+**Description:** Boolean logic is hard to scan. Extract conditions into functions with
+meaningful names. `if (shouldBeDeleted(timer))` reads like prose. `if (timer.hasExpired() && !timer.isRecurrent())`
+requires the reader to parse logic rather than understand intent.
+**Test question:** Can the condition be extracted into a function whose name expresses
+what the condition means?
+
+### G29 — Avoid Negative Conditionals
+**Code:** G29  
+**Description:** Negative conditionals are harder to understand than positive ones.
+`buffer.shouldCompact()` is easier to parse than `!buffer.shouldNotCompact()`. Prefer
+the positive form. When you need the negative, double-negatives (`not not`) are never acceptable.
+**Test question:** Is this conditional expressed in its positive form?
+
+---
+
+## Comments
+
+### C5 — Commented-Out Code
+**Code:** C5  
+**Description:** Commented-out code is an abomination. No one will delete it because
+everyone assumes someone else put it there for a reason. It accumulates like sediment.
+Delete it. Version control remembers everything. This is the single most important
+comment smell to eliminate.
+**Test question:** Is there any code that has been commented out?
+
+### C3 — Redundant Comments
+**Code:** C3  
+**Description:** A comment that describes exactly what the code already says clearly
+is pure noise. It clutters the file, takes time to read, and can drift out of sync.
+If the code is clear, the comment is unnecessary. If the comment adds nothing, remove it.
+**Test question:** Could you delete this comment and lose no information?
+
+### C2 — Obsolete Comments
+**Code:** C2  
+**Description:** Comments age badly. A comment that was accurate when written becomes
+misleading after the code changes. Misleading comments are worse than no comments —
+they actively corrupt the reader's mental model.
+**Test question:** Does this comment accurately describe what the code currently does?
+
+### Intent vs. Explanation
+**Code:** (general — Ch. 4)  
+**Description:** The only valuable comments explain *why* — intent, rationale, warnings.
+Comments that explain *what* the code does are redundant with the code itself. Invest in
+renaming and restructuring until the *what* is obvious; then write a comment only if
+the *why* is not.
+**Test question:** Does this comment explain *why* rather than *what*?
+
+---
+
+## Error Handling
+
+### Don't Return Null
+**Code:** (Ch. 7)  
+**Description:** Every null return is a potential NullPointerException waiting to happen.
+If a function can return null, every caller must check — and one check missed causes a
+runtime crash. Return a Special Case object (`Collections.emptyList()`, `NullEmployee`),
+throw an exception, or use Optional.
+**Test question:** Does this function return null to indicate failure or absence?
+
+### Don't Pass Null
+**Code:** (Ch. 7)  
+**Description:** Passing null as a function argument is even worse than returning it.
+There is no reasonable way for a function to handle an argument being null except with
+defensive checks throughout. Use overloading, Optional, or default values instead.
+**Test question:** Is null passed as an argument to any function?
+
+### Exceptions Carry Context
+**Code:** (Ch. 7)  
+**Description:** A thrown exception should tell the receiver what operation failed and
+why. An exception message of "Error" or a bare stack trace is useless in a log.
+Include the operation being attempted and the failure type.
+**Test question:** Does this exception message tell a reader what operation failed and why?
+
+### Special Case Pattern
+**Code:** (Ch. 7, Martin Fowler)  
+**Description:** When a function is asked for something that might not exist
+(a customer with no orders, a user with no profile), returning null forces every
+caller to handle the absence. The Special Case pattern encapsulates the "nothing here"
+behavior into an object that behaves like the real thing — callers don't need to check.
+**Test question:** Is there a null check that could be replaced with a Special Case object?
+
+---
+
+## Objects and Data Structures
+
+### G36 — Law of Demeter (Avoid Transitive Navigation)
+**Code:** G36  
+**Description:** Code should not navigate through a chain of objects to get at behavior
+deep inside the structure: `a.getB().getC().doSomething()`. This couples the caller to
+the entire chain. Expose what you need directly, or restructure so each class talks
+only to its immediate collaborators.
+**Test question:** Does this line navigate more than one association to get at behavior?
+
+### G14 — Feature Envy
+**Code:** G14  
+**Description:** A method that uses another class's data more than its own is envious
+of that class. This is a sign the method probably belongs in the other class. Move the
+behavior to where the data lives.
+**Test question:** Does this method use more fields or methods of another class than its own?
+
+### G23 — Prefer Polymorphism to Switch/If-Else Chains
+**Code:** G23  
+**Description:** `switch` statements that check a type tag repeat themselves across the
+codebase. When you add a new type, you must find and update every switch. Polymorphism
+centralizes the variation in one place — the class hierarchy.
+**Test question:** Does this switch or if-else chain select behavior based on a type tag?
+
+---
+
+## Classes
+
+### Single Responsibility Principle
+**Code:** (Ch. 10)  
+**Description:** A class should have one, and only one, reason to change. If you can
+describe what a class does only by using "and" or "or," it has more than one responsibility.
+A class with multiple responsibilities is coupled to multiple change vectors.
+**Test question:** Can this class be described in one sentence without "and" or "or"?
+
+### G8 — Too Much Information
+**Code:** G8  
+**Description:** Well-defined interfaces expose little and demand little. A class with
+many public methods, or a data class with many public fields, is hard to understand
+and hard to change. The best interfaces hide almost everything.
+**Test question:** Does this interface expose more than the caller absolutely needs?
+
+### Open-Closed Principle
+**Code:** (Ch. 10)  
+**Description:** Classes should be open for extension but closed for modification.
+When new behavior is needed, new code should be added — not existing code changed.
+This is achieved through abstraction: depend on interfaces, not concretions.
+**Test question:** Would adding a new variant of this behavior require modifying existing classes?
+
+---
+
+## Systems and Boundaries
+
+### G35 — Keep Configurable Data at High Levels
+**Code:** G35  
+**Description:** Constants and configurable data (server addresses, timeout values,
+feature limits) should be defined at the top of the system and passed down. Burying
+a magic constant deep inside a business function makes it invisible and fragile.
+**Test question:** Are there constants buried in low-level logic that should be defined at a higher level?
+
+### Wrap Third-Party APIs
+**Code:** (Ch. 8)  
+**Description:** Third-party interfaces should not scatter through your codebase.
+Wrap them in your own abstraction so you control the vocabulary, can mock them in tests,
+and can swap them with a single change. The wrapping point is the clean boundary.
+**Test question:** Can you change the underlying third-party library by modifying only one class?
+
+### G13 — Artificial Coupling
+**Code:** G13  
+**Description:** Coupling two modules that have no structural reason to be related forces
+them to change together. Artificial coupling often appears as a utility function placed
+in a class because it was convenient, or a constant defined in a class that has nothing
+to do with it.
+**Test question:** Does this module have a dependency that exists only for convenience, not structure?
+
+---
+
+## Tests
+
+### T1 — Insufficient Tests
+**Code:** T1  
+**Description:** A test suite is insufficient if it does not cover everything that could
+possibly break. Developers must not be satisfied by a coverage number — they must think
+about what the code does and verify each behavior.
+**Test question:** Is there any behavior in this code that no test exercises?
+
+### T5 — Test Boundary Conditions
+**Code:** T5  
+**Description:** Bugs hide at the edges. Empty collections, zero values, maximum values,
+negative numbers, null inputs — boundary conditions are exactly where assumptions break.
+Every algorithm has its edges; every edge deserves a test.
+**Test question:** Are the minimum, maximum, and edge-case inputs tested?
+
+### F.I.R.S.T.
+**Code:** (Ch. 9)  
+**Description:** Good tests are Fast (run in milliseconds), Independent (no order dependency),
+Repeatable (same result in any environment), Self-validating (pass or fail, no manual check),
+and Timely (written with the production code). Tests that violate these are not maintained.
+**Test question:** Can every test in this suite be run in isolation, in any order, in any environment?

package/clean-code-reviewer/references/review-checklist.md

@@ -0,0 +1,254 @@
+# Clean Code — Code Review Checklist
+
+Systematic checklist for reviewing code against the principles from Robert C. Martin's
+*Clean Code: A Handbook of Agile Software Craftsmanship*.
+
+---
+
+## Chapter 2 — Meaningful Names
+
+### Intention and Clarity
+- [ ] **N1 — Descriptive names** — Does every name (variable, function, class) tell you *why* it exists, *what* it does, and *how* it's used? Would a name require a comment to explain it?
+- [ ] **N4 — Unambiguous names** — Is each name precise and unambiguous? Could `rename()` instead be `renamePageAndOptionallyAllReferences()`? Would a more specific name prevent confusion?
+- [ ] **N2 — Appropriate abstraction level** — Do names match the level of abstraction of the code? Is `dial(phoneNumber)` where `connect(connectionLocator)` would be more general and honest?
+
+### Avoiding Misinformation and Noise
+- [ ] **No disinformation** — Do any names actively mislead? Is `accountList` actually not a `List`? Are platform abbreviations (`hp`, `aix`, `sco`) used as variable names?
+- [ ] **No meaningless distinctions** — Are names meaningfully different from each other? Is there `ProductData` vs. `ProductInfo`, `data` vs. `info`, `a1` vs. `a2`? Noise words add nothing.
+- [ ] **N6 — No encodings** — Is there Hungarian notation, `m_` member prefixes, or `I`-prefixed interface names? Modern IDEs make these unnecessary.
+
+### Conventions and Consistency
+- [ ] **Class names** — Are class names nouns or noun phrases (`Customer`, `WikiPage`, `Account`)? Are vague names like `Manager`, `Processor`, `Data`, `Info` avoided?
+- [ ] **Method names** — Are method names verbs or verb phrases (`postPayment`, `deletePage`, `save`)? Do accessors, mutators, and predicates use `get`/`set`/`is` prefixes?
+- [ ] **One word per concept** — Is one consistent word used per abstract concept across the codebase? Is the code mixing `fetch`, `retrieve`, and `get` for equivalent operations?
+- [ ] **No puns** — Is the same word used for two different purposes? Does `add` mean "concatenate" in one place and "insert into collection" in another?
+- [ ] **N3 — Standard nomenclature** — Are design pattern names used when patterns are applied (`AccountVisitor`, `JobQueue`)? Does code near domain concepts use domain vocabulary?
+- [ ] **N5 — Scope-appropriate length** — Is `i` used in a 5-line loop but a 500-line scope? The length of a name should correspond to the size of its scope.
+
+### Context
+- [ ] **Meaningful context** — Does `state` alone appear where `addrState` or an `Address` class would clarify? Does the surrounding structure provide context?
+- [ ] **No gratuitous context** — Are class or variable names prefixed with an application abbreviation (e.g., every class starting with `GSD`)? Short, clear names are better.
+- [ ] **Pronounceable** — Could every name be discussed in conversation? Is `genymdhms` used where `generationTimestamp` belongs?
+- [ ] **Searchable** — Are single-letter variables and magic numbers scoped to very short blocks where their meaning is unambiguous?
+
+---
+
+## Chapter 3 — Functions
+
+### Size and Focus
+- [ ] **Small** — Are functions short? Does each block within `if`, `else`, and `while` resolve to one line, ideally a function call? Would any function fit on one screen?
+- [ ] **G30 / Do one thing** — Can you extract a meaningfully named function from the body? If yes, the function is doing more than one thing.
+- [ ] **One level of abstraction** — Does the function mix high-level intent (e.g., `renderPage()`) with low-level manipulation (e.g., direct string concatenation)? Functions should read top-down, each leading to the next level of abstraction (the Stepdown Rule).
+- [ ] **G34 — Descend only one level** — Does each function descend exactly one level of abstraction below the function's stated name?
+
+### Arguments
+- [ ] **F1 — Argument count** — Does any function take more than three arguments? Three requires strong justification. More than three: extract into an argument object.
+- [ ] **F3 — Flag arguments** — Does any function take a boolean parameter? A flag argument loudly declares the function does two things. Split it into two functions.
+- [ ] **F2 — Output arguments** — Does any argument serve as an output? Output arguments are counterintuitive. Use return values, or use `this`/`self`.
+- [ ] **Argument objects** — When 2-3 arguments are closely related (e.g., `x, y, radius`), should they be grouped into an object (`Point center, double radius`)?
+
+### Side Effects and Structure
+- [ ] **No side effects** — Does a function named `checkPassword` also initialize a session? Does a function do something other than what its name says?
+- [ ] **Command-Query Separation** — Does any function both modify state *and* return a value? Functions should either do something or answer something, never both.
+- [ ] **F4 — Dead functions** — Are there functions that are never called? Delete them; version control remembers.
+- [ ] **G5 — No duplication** — Is any algorithm, validation rule, or business logic repeated? Is TEMPLATE METHOD or STRATEGY applicable?
+
+### Error Handling
+- [ ] **Exceptions over return codes** — Are error conditions signaled by throwing exceptions rather than returning error codes?
+- [ ] **Error handling is one thing** — If a function has a `try` block, does the function do *only* error handling? Are the bodies of `try` and `catch` extracted into their own functions?
+- [ ] **Switch statements** — If a switch statement exists, is it buried in an abstract factory that uses polymorphism? Is it the only such switch in the codebase for that type?
+
+---
+
+## Chapter 4 — Comments
+
+### Bad Comments to Eliminate
+- [ ] **C5 — Commented-out code** — Is there any code that has been commented out? Delete it. Version control remembers. This is the worst comment smell.
+- [ ] **C3 — Redundant comments** — Does any comment restate what the code already says clearly? (`i++; // increment i`). Does the comment take longer to read than the code?
+- [ ] **C2 — Obsolete comments** — Do any comments describe behavior that the code no longer performs? Have comments drifted from the code they annotate?
+- [ ] **C1 — Inappropriate information** — Do comments contain changelogs, author attributions, dates, or metadata that belongs in version control?
+- [ ] **C4 — Poorly written comments** — Are any comments grammatically wrong, rambling, or unclear? If a comment is worth writing, it's worth writing well.
+- [ ] **Noise comments** — Are there comments like `/** Default constructor */` or `/** The day of the month */` that state the obvious?
+- [ ] **Closing brace comments** — Are there comments like `} // while` or `} // if`? These indicate functions that are too long. Shorten the function instead.
+- [ ] **Byline comments** — Are there `// Added by Rick` comments? Version control tracks authorship.
+
+### Good Comments to Verify
+- [ ] **Intent comments** — Do comments explain *why* a decision was made, not *what* the code does? This is the only comment form that adds value not already in the code.
+- [ ] **Warning comments** — Are there consequences worth warning future developers about (e.g., `// Don't run unless you have time to kill`)?
+- [ ] **TODO comments** — Are TODO comments specific and actionable? Are they tracked and not accumulating as permanent clutter?
+- [ ] **Public API documentation** — Do all public APIs have clear documentation comments that explain parameters, return values, and exceptions?
+
+---
+
+## Chapter 5 — Formatting
+
+- [ ] **Newspaper metaphor** — Does each source file read like a newspaper? Is the class name at the top, high-level abstractions near the top, and details near the bottom?
+- [ ] **Vertical openness** — Are separate concepts separated by blank lines? Can distinct sections (imports, fields, methods) be visually distinguished?
+- [ ] **Vertical density** — Are closely related lines grouped tightly together without blank lines breaking up what belongs together?
+- [ ] **Vertical distance** — Are variables declared close to their first use? Are related functions close to each other, with callers above callees?
+- [ ] **Line length** — Are all lines short enough to avoid horizontal scrolling? Is a consistent maximum line length enforced across the team?
+- [ ] **Team rules** — Does the formatting match team conventions? Is an automated formatter (Prettier, Black, ktlint, gofmt) enforced?
+
+---
+
+## Chapter 6 — Objects and Data Structures
+
+- [ ] **Data/Object anti-symmetry** — Is data hiding appropriate? Do objects expose behavior and hide data? Do data structures expose data and have no significant behavior?
+- [ ] **G36 / Law of Demeter** — Does any method call a method on an object returned by another method (`a.getB().getC().doSomething()`)? Does the code navigate association chains it should not know about?
+- [ ] **No train wrecks** — Are chained method calls (`a.getB().getC().getD()`) broken up into intermediate variables or redesigned?
+- [ ] **No hybrids** — Are there classes that are half-object (hiding data behind methods) and half-data structure (exposing fields directly)? These are the worst of both worlds.
+- [ ] **DTOs** — Are Data Transfer Objects (database rows, API payloads) simple data structures with public fields and no behavior?
+
+---
+
+## Chapter 7 — Error Handling
+
+- [ ] **Exceptions over return codes** — Are all error conditions communicated by exceptions, not return codes or sentinel values?
+- [ ] **Try-catch-finally first** — When writing functions that can fail, does the structure start with the `try-catch-finally` to define the transaction boundary?
+- [ ] **Context with exceptions** — Do thrown exceptions include the failed operation and the type of failure? Are raw stack traces the only diagnostic?
+- [ ] **Caller-defined exception classes** — Are third-party exceptions wrapped into a common type that the caller needs, rather than leaking library-specific exception hierarchies?
+- [ ] **Special Case pattern** — Is null returned where a Special Case object (e.g., `NullEmployee`, `Collections.emptyList()`) would let the caller avoid special-case logic?
+- [ ] **Don't return null** — Does any function return `null` to indicate failure or absence? Every null return is a potential crash. Return a Special Case object or throw.
+- [ ] **Don't pass null** — Is `null` passed as a function argument? This forces defensive null checks everywhere. Use Optional, overloading, or a Special Case.
+
+---
+
+## Chapter 8 — Boundaries
+
+- [ ] **Wrap third-party APIs** — Are third-party interfaces accessed directly throughout the codebase? Do you control the vocabulary for the dependency, or does the dependency control yours?
+- [ ] **Learning tests** — Are third-party APIs explored and verified through learning tests? Do these tests serve as living documentation of expected behavior?
+- [ ] **Clean boundaries** — Is third-party knowledge isolated to specific adapter/wrapper classes? Would a library swap require changes in more than one place?
+
+---
+
+## Chapter 9 — Unit Tests
+
+### Test Quality
+- [ ] **T1 — Sufficient tests** — Does the test suite cover everything that could possibly break? Are there critical paths, edge cases, or error conditions with no tests?
+- [ ] **Readable tests** — Is each test readable? Does it follow BUILD-OPERATE-CHECK (Arrange-Act-Assert / Given-When-Then)?
+- [ ] **One concept per test** — Does each test verify one and only one concept? When a test fails, is it immediately obvious what is broken?
+- [ ] **T3 — No skipped trivial tests** — Are trivial tests skipped or deleted? Even trivial tests have documentary value.
+- [ ] **T4 — Ignored tests documented** — Are any tests marked as skipped or ignored? Does each have a clear note about the ambiguity or open question it represents?
+
+### F.I.R.S.T. Properties
+- [ ] **T9 — Fast** — Do all tests run quickly? Would slow tests cause developers to avoid running them?
+- [ ] **Independent** — Do tests depend on each other? Can they be run in any order?
+- [ ] **Repeatable** — Do tests pass in every environment (local, CI, other machines)?
+- [ ] **Self-validating** — Do tests produce a clear pass/fail with no manual inspection required?
+- [ ] **Timely** — Were tests written alongside or before the production code they cover?
+
+### Coverage and Boundaries
+- [ ] **T2 — Coverage tool** — Is a coverage tool being used? Are coverage gaps reviewed, not just a coverage number?
+- [ ] **T5 — Boundary conditions** — Are boundary conditions tested? Off-by-one errors, empty collections, maximum sizes, negative values?
+- [ ] **T6 — Near bugs** — When a bug is found and fixed, are exhaustive tests added for the surrounding code? Bugs cluster.
+- [ ] **T7 — Failure patterns** — Do test failures form a pattern? Can that pattern diagnose the root cause rather than a symptom?
+- [ ] **T8 — Coverage patterns** — Does the pattern of uncovered code reveal structural problems?
+
+---
+
+## Chapter 10 — Classes
+
+- [ ] **Small (by responsibility)** — Is each class small? Measured not in lines but in *responsibilities*. Can you describe what the class does without using "and" or "or"?
+- [ ] **Single Responsibility Principle** — Does each class have one, and only one, reason to change? Is there any mixing of business logic, persistence, presentation, or logging?
+- [ ] **High cohesion** — Do most methods in the class use most of the instance variables? Are there methods that touch only 1-2 fields — a sign they belong elsewhere?
+- [ ] **Open-Closed Principle** — Can the behavior of the class be extended without modifying it? Do new features require changing existing classes, or adding new ones?
+- [ ] **Dependency Inversion** — Do high-level classes depend on abstractions (interfaces/abstract classes) rather than concrete implementations?
+
+---
+
+## Chapter 11 — Systems
+
+- [ ] **Separate construction from use** — Is object construction (dependency wiring) mixed into business logic? Construction should happen at startup; business logic should work with already-built objects.
+- [ ] **Dependency injection** — Are dependencies injected rather than instantiated inside classes? Does any business logic call `new` on a concrete class it shouldn't know about?
+- [ ] **Cross-cutting concerns** — Are cross-cutting concerns (logging, security, transactions) handled through aspects, decorators, or interceptors rather than scattered throughout business logic?
+- [ ] **G35 — Configurable data at high levels** — Are magic constants and configurable values (hostnames, limits, feature flags) defined at the top level and passed down, not buried deep in low-level code?
+
+---
+
+## Chapter 17 — Smells and Heuristics (Full Heuristic Reference)
+
+### Comments (C-codes)
+- [ ] **C1** — Does any comment contain changelog entries, author names, dates, or other metadata that belongs in version control?
+- [ ] **C2** — Does any comment describe behavior that the current code no longer performs? Is it stale?
+- [ ] **C3** — Does any comment simply restate what the code says clearly on its own?
+- [ ] **C4** — Is any comment poorly written, rambling, or grammatically incorrect?
+- [ ] **C5** — Is there any commented-out code? Delete it immediately.
+
+### General (G-codes)
+- [ ] **G1** — Does any source file contain code in multiple languages (HTML embedded in Java, SQL inline in Python)?
+- [ ] **G2** — Does the code implement what a reader would obviously expect from the function/class name? (Principle of Least Surprise)
+- [ ] **G3** — Has the code been tested at all boundary conditions? Not just the happy path.
+- [ ] **G4** — Are any safeties disabled? Overridden warnings? Silently caught exceptions? Commented-out assertions?
+- [ ] **G5** — Is any code, algorithm, or business rule duplicated? Every duplication should be addressed with TEMPLATE METHOD, STRATEGY, or extraction.
+- [ ] **G6** — Are any methods or variables at the wrong level of abstraction? Do lower-level details appear in higher-level classes?
+- [ ] **G7** — Do any base classes import or depend on their derived classes?
+- [ ] **G8** — Do any interfaces expose more methods than the caller needs? Do data classes expose more fields than necessary?
+- [ ] **G9** — Is there any unreachable code, dead conditional branches, or functions that can never be called?
+- [ ] **G10** — Are variables or utility functions defined far from where they are used?
+- [ ] **G11** — Is the same concept handled differently in different parts of the codebase?
+- [ ] **G12** — Is there clutter: unused variables, empty constructors, functions that are never called?
+- [ ] **G13** — Are there artificial couplings between modules that share no structural relationship?
+- [ ] **G14** — Do methods use data from another class more than their own? Feature Envy — move the method closer to the data.
+- [ ] **G15** — Do any functions take boolean or enum selector arguments to choose behavior? Split into separate functions.
+- [ ] **G16** — Are there magic numbers, Hungarian notation, or run-on expressions that obscure intent?
+- [ ] **G17** — Is any functionality placed in a surprising module or class? (Principle of Least Surprise for placement)
+- [ ] **G18** — Are there static methods that should be instance methods? Would the behavior need to vary polymorphically?
+- [ ] **G19** — Are complex calculations broken into named intermediate variables that explain each step?
+- [ ] **G20** — Does `date.add(5)` exist where `date.addDays(5)` would be clearer? Do function names say what they do?
+- [ ] **G21** — Is there any algorithm that was arrived at by trial-and-error? Does the author understand why the algorithm works?
+- [ ] **G22** — Does any module assume something about another module without making that assumption explicit in the structure?
+- [ ] **G23** — Are there `if/else` or `switch/case` chains where polymorphism would be cleaner and more extensible?
+- [ ] **G24** — Does the code follow the team's standard conventions for naming, formatting, and structure?
+- [ ] **G25** — Are there magic numbers (3, 86400, 0.01) that should be named constants?
+- [ ] **G26** — Is float used for currency? Are concurrent data structures used without locks? Is precision being assumed where it must be enforced?
+- [ ] **G27** — Is a naming convention used where an abstract method would force compliance? (`switch` on type tag vs. polymorphic method)
+- [ ] **G28** — Are complex conditionals extracted into descriptive boolean functions? (`if (shouldBeDeleted(timer))` vs. `if (timer.hasExpired() && !timer.isRecurrent())`)
+- [ ] **G29** — Are conditionals written positively where possible? (`if (buffer.shouldCompact())` vs. `if (!buffer.shouldNotCompact())`)
+- [ ] **G30** — Do functions do more than one thing? (Same as Ch. 3 — "Do one thing")
+- [ ] **G31** — Are there hidden temporal couplings where one function must be called before another with no structural enforcement?
+- [ ] **G32** — Is there unexplained structure — decisions made without a discernible reason?
+- [ ] **G33** — Are boundary conditions (`level + 1`, `offset + 1`) encapsulated in explanatory variables rather than scattered inline?
+- [ ] **G34** — Do functions descend more than one level of abstraction below the function's name?
+- [ ] **G35** — Are configurable constants buried deep in a function body rather than defined at the highest meaningful level?
+- [ ] **G36** — Does any code reach through a chain of associations to get at data? (`a.getB().getC()`) — Law of Demeter violation.
+
+### Names (N-codes)
+- [ ] **N1** — Are all names descriptive? Do they make the code readable on its own?
+- [ ] **N2** — Are names appropriate for the level of abstraction? Not too specific, not too vague?
+- [ ] **N3** — Are standard names from design patterns and domain language used where applicable?
+- [ ] **N4** — Are names precise enough to be unambiguous between similar concepts?
+- [ ] **N5** — Do names scale in length with their scope? Long names for long-lived variables, short for tightly scoped.
+- [ ] **N6** — Is there any encoding in names (Hungarian notation, `m_` prefix, type suffixes)?
+- [ ] **N7** — Do function names describe side effects? Does `getOos()` that creates an object need to be `createOrReturnOos()`?
+
+### Tests (T-codes)
+- [ ] **T1** — Does the test suite cover all logic that could possibly break?
+- [ ] **T2** — Is a coverage tool being used and its output reviewed?
+- [ ] **T3** — Are trivial tests present? They have documentary value even if they seem obvious.
+- [ ] **T4** — Are ignored/skipped tests marked with a note explaining the open question?
+- [ ] **T5** — Are boundary conditions tested?
+- [ ] **T6** — When a bug is fixed, are exhaustive tests added for the surrounding logic?
+- [ ] **T7** — Are patterns of test failure used to diagnose root causes?
+- [ ] **T8** — Is the pattern of uncovered code analyzed for structural insight?
+- [ ] **T9** — Do all tests run fast enough that developers run them frequently?
+
+---
+
+## Quick Review Workflow
+
+1. **Naming pass** — Read every name. Does each name reveal intent? Would any name require a comment to explain it?
+2. **Function pass** — Evaluate each function: size, argument count, single responsibility, no side effects, no flag args.
+3. **Comment audit** — Eliminate C1-C5 smells. Verify any surviving comments add intent not present in the code.
+4. **Structure check** — Formatting, vertical distance, newspaper metaphor, class cohesion.
+5. **Error handling** — No null returns, no error codes, exceptions with context, Special Case pattern where applicable.
+6. **G-code scan** — Run through G1-G36 for systemic smells.
+7. **Test quality** — F.I.R.S.T., T1-T9, one concept per test, boundary conditions.
+
+## Severity Levels
+
+| Severity | Description | Examples |
+|----------|-------------|---------|
+| **Critical** | Fundamentally undermines readability or introduces likely bugs | Commented-out code (C5), null returns on failure, disabled safeties (G4), dead code (G9) |
+| **High** | Meaningful quality violations that should be fixed | Flag arguments (F3), train wrecks (G36), feature envy (G14), insufficient tests (T1) |
+| **Medium** | Non-idiomatic patterns that hurt long-term maintainability | Magic numbers (G25), negative conditionals (G29), missing boundary tests (T5), misleading names |
+| **Low** | Polish and refinements | Noise comments (C3), missing explanatory variables (G19), minor convention violations (G24) |