docq 0.1.0__tar.gz

docq-0.1.0/.claude/skills/software-design-philosophy/SKILL.md

@@ -0,0 +1,280 @@
+---
+name: software-design-philosophy
+description: 'Manage software complexity through deep modules, information hiding, and strategic programming. This skill is a practical breakdown of the principles from John Ousterhout's "A Philosophy Of Software Design". Use when designing a new complex feature or when refactoring existing complex code to apply these principles.'
+license: MIT
+metadata:
+  author: wondelai
+  version: "1.2.0"
+---
+
+# A Philosophy of Software Design Framework
+
+A practical framework for managing the fundamental challenge of software engineering: complexity. Apply these principles when designing modules, reviewing APIs, refactoring code, or advising on architecture decisions. The central thesis is that complexity is the root cause of most software problems, and managing it requires deliberate, strategic thinking at every level of design.
+
+## Core Principle
+
+**The greatest limitation in writing software is our ability to understand the systems we are creating.** Complexity is the enemy. It makes systems hard to understand, hard to modify, and a source of bugs. Every design decision should be evaluated by asking: "Does this increase or decrease the overall complexity of the system?" The goal is not zero complexity -- that is impossible in useful software -- but to minimize unnecessary complexity and concentrate necessary complexity where it can be managed.
+
+## Consulting the Source (gloss corpus)
+
+This repo may carry a queryable corpus of the book itself: `gloss` returns Ousterhout's
+**actual passages** with citations, not a paraphrase. When the corpus is available,
+ground design answers in it — a verbatim passage with a page number beats this file's
+distillation.
+
+**Availability check:** the corpus db is `build/minimax-v2.db`; if that file is absent,
+use the live db named in `CLAUDE.md`. If no db exists, skip this section and work from
+the bundled [reference files](#reference-files) as usual.
+
+**How to query:**
+
+```bash
+uv run gloss retrieve "<symptom-phrased query>" --db build/minimax-v2.db -k 3 --compact
+```
+
+- Phrase the query as a developer's *symptom* ("callers have to call setup in the right
+  order", "my class just forwards calls and adds nothing"), not book vocabulary
+  ("temporal decomposition").
+- **Rewrite before you query.** Expand a terse, noisy, or multi-concern situation into
+  ONE complete symptom sentence covering ONE concern ("big function split?" → "is a long
+  function that does several sequential things automatically a problem"); fire separate
+  queries for separate concerns. Measured effect: ~+7 points hit@1 on realistic queries.
+  If the situation is already a well-formed single-concern symptom sentence, use it
+  as-is — over-elaborating an already-sharp query makes results worse.
+- When you already know which principle applies, narrow with `--principle <slug>`. The
+  slugs are the six principles below: `complexity`, `deep-modules`,
+  `information-hiding`, `general-purpose`, `comments`, `strategic-programming`.
+
+**Reading the output:** the top hit prints in full — citation header + verbatim
+passage. Runners-up print as one `more: id=N [citation] (type via tags) — <paraphrase>`
+preview line each.
+
+**Trust rules:**
+
+- Top hit tagged `via lex#N+sem#M` (both channels present) = two independent retrieval
+  signals agree — high confidence; quote it.
+- Channels disagree (one-channel tag like `via sem#4`), or a `more:` preview matches
+  the situation better than the top hit? Expand that unit before answering:
+  `uv run gloss show <id> --db build/minimax-v2.db`.
+- **Never answer from a preview line.** Its text is a generated paraphrase, not the
+  passage — the verbatim promise applies only to passage bodies. Expand with
+  `gloss show` and quote the source's own words.
+- No hits, or nothing fits the situation? Rephrase once with different symptom
+  vocabulary. Still nothing → fall back to the bundled reference files.
+
+**Cite what you quote:** pass the citation through — `[deep-modules §4.6 p.45]` tells
+the reader exactly where in the book the passage lives.
+
+## Scoring
+
+**Goal: 10/10.** When reviewing or creating software designs, rate them 0-10 based on adherence to the principles below. A 10/10 means deep modules with clean abstractions, excellent information hiding, strategic thinking about complexity, and comments that capture design intent. Lower scores indicate shallow modules, information leakage, tactical shortcuts, or missing design documentation. Always provide the current score and specific improvements needed to reach 10/10.
+
+## The Software Design Framework
+
+Six principles for managing complexity and producing systems that are easy to understand and modify:
+
+### 1. Complexity and Its Causes
+
+**Core concept:** Complexity is anything related to the structure of a software system that makes it hard to understand and modify. It manifests through three symptoms: change amplification, cognitive load, and unknown unknowns.
+
+**Why it works:** By identifying the specific symptoms of complexity, developers can diagnose problems precisely rather than relying on vague notions of "messy code." The two fundamental causes -- dependencies and obscurity -- provide clear targets for design improvement.
+
+**Key insights:**
+- Change amplification: a simple change requires modifications in many places
+- Cognitive load: a developer must hold too much information in mind to make a change
+- Unknown unknowns: it is not obvious what needs to be changed, or what information is relevant (the worst symptom)
+- Dependencies: code cannot be understood or modified in isolation
+- Obscurity: important information is not obvious from the code or documentation
+- Complexity is incremental -- it accumulates from hundreds of small decisions, not one big mistake
+- The "death by a thousand cuts" nature of complexity means every decision matters
+
+**Code applications:**
+
+| Context | Pattern | Example |
+|---------|---------|---------|
+| **Change amplification** | Centralize shared knowledge | Extract color constants instead of hardcoding `#ff0000` in 20 files |
+| **Cognitive load** | Reduce what developers must know | Use a simple `open(path)` API instead of requiring buffer size, encoding, and lock mode |
+| **Unknown unknowns** | Make dependencies explicit | Use type systems and interfaces to surface what a change affects |
+| **Dependency management** | Minimize cross-module coupling | Pass data through well-defined interfaces, not shared global state |
+| **Obscurity reduction** | Name things precisely | `numBytesReceived` not `n`; `retryDelayMs` not `delay` |
+
+See: [references/complexity-symptoms.md](references/complexity-symptoms.md)
+
+### 2. Deep vs Shallow Modules
+
+**Core concept:** The best modules are deep: they provide powerful functionality behind a simple interface. Shallow modules have complex interfaces relative to the functionality they provide, adding complexity rather than reducing it.
+
+**Why it works:** A module's interface represents the complexity it imposes on the rest of the system. Its implementation represents the functionality it provides. Deep modules give you a high ratio of functionality to interface complexity. The interface is the cost; the implementation is the benefit.
+
+**Key insights:**
+- A module's depth = functionality provided / interface complexity imposed
+- Deep modules: simple interface, powerful implementation (Unix file I/O, garbage collectors)
+- Shallow modules: complex interface, limited implementation (Java I/O wrapper classes)
+- "Classitis": the disease of creating too many small, shallow classes
+- Each interface adds cognitive load -- more classes does not mean better design
+- The best abstractions hide significant complexity behind a few simple concepts
+- Small methods are not inherently good; depth matters more than size
+
+**Code applications:**
+
+| Context | Pattern | Example |
+|---------|---------|---------|
+| **Deep module** | Hide complexity behind simple API | `file.read(path)` hides disk blocks, caching, buffering, encoding |
+| **Shallow module** | Avoid thin wrappers that just pass through | A `FileInputStream` wrapped in `BufferedInputStream` wrapped in `ObjectInputStream` |
+| **Classitis cure** | Merge related shallow classes | Combine `RequestParser`, `RequestValidator`, `RequestProcessor` into one `RequestHandler` |
+| **Method depth** | Methods should do something substantial | A `delete(key)` that handles locking, logging, cache invalidation, and rebalancing |
+| **Interface simplicity** | Fewer parameters, fewer methods | `config.get(key)` with sensible defaults, not 15 constructor parameters |
+
+See: [references/deep-modules.md](references/deep-modules.md)
+
+### 3. Information Hiding and Leakage
+
+**Core concept:** Each module should encapsulate knowledge that is not needed by other modules. Information leakage -- when a design decision is reflected in multiple modules -- is one of the most important red flags in software design.
+
+**Why it works:** When information is hidden inside a module, changes to that knowledge require modifying only that module. When information leaks across module boundaries, changes propagate through the system. Information hiding reduces both dependencies and obscurity, the two fundamental causes of complexity.
+
+**Key insights:**
+- Information hiding: embed knowledge of a design decision in a single module
+- Information leakage: the same knowledge appears in multiple modules (a red flag)
+- Temporal decomposition causes leakage: splitting code by when things happen forces shared knowledge across phases
+- Back-door leakage through data formats, protocols, or shared assumptions is the subtlest form
+- Decorators are frequent sources of leakage -- they expose the decorated interface
+- If two modules share knowledge, consider merging them or creating a new module that encapsulates the shared knowledge
+
+**Code applications:**
+
+| Context | Pattern | Example |
+|---------|---------|---------|
+| **Information hiding** | Encapsulate format details | One module owns the HTTP parsing logic; callers get structured objects |
+| **Temporal decomposition** | Organize by knowledge, not time | Combine "read config" and "apply config" into a single config module |
+| **Format leakage** | Centralize serialization | One module handles JSON encoding/decoding rather than spreading `json.dumps` everywhere |
+| **Protocol leakage** | Abstract protocol details | A `MessageBus.send(event)` hides whether transport is HTTP, gRPC, or queue |
+| **Decorator leakage** | Use deep wrappers sparingly | Prefer adding buffering inside the file class over wrapping it externally |
+
+See: [references/information-hiding.md](references/information-hiding.md)
+
+### 4. General-Purpose vs Special-Purpose Modules
+
+**Core concept:** Design modules that are "somewhat general-purpose": the interface should be general enough to support multiple uses without being tied to today's specific requirements, while the implementation handles current needs. Ask: "What is the simplest interface that will cover all my current needs?"
+
+**Why it works:** General-purpose interfaces tend to be simpler because they eliminate special cases. They also future-proof the design since new use cases often fit the existing abstraction. However, over-generalization wastes effort and can itself introduce complexity through unnecessary abstractions.
+
+**Key insights:**
+- "Somewhat general-purpose" is the sweet spot between too specific and too generic
+- The key question: "What is the simplest interface that will cover all my current needs?"
+- General-purpose interfaces are often simpler than special-purpose ones (fewer special cases)
+- Push complexity downward: modules at lower levels should handle hard cases so upper levels stay simple
+- Configuration parameters often represent failure to determine the right behavior -- each parameter is complexity pushed to the caller
+- When in doubt, implement the simpler, more general-purpose approach first
+
+**Code applications:**
+
+| Context | Pattern | Example |
+|---------|---------|---------|
+| **API generality** | Design for the concept, not one use case | A `text.insert(position, string)` API instead of `text.addBulletPoint()` |
+| **Push complexity down** | Handle defaults in the module | A web server that picks reasonable buffer sizes instead of requiring callers to configure them |
+| **Reduce configuration** | Determine behavior automatically | Auto-detect file encoding instead of requiring an `encoding` parameter |
+| **Avoid over-specialization** | Remove use-case-specific methods | One `store(key, value, options)` instead of `storeUser()`, `storeProduct()`, `storeOrder()` |
+| **Somewhat general** | General interface, specific implementation | A `Datastore` interface that currently backs onto PostgreSQL but does not expose SQL concepts |
+
+See: [references/general-vs-special.md](references/general-vs-special.md)
+
+### 5. Comments as Design Documentation
+
+**Core concept:** Comments should describe things that are not obvious from the code. They capture design intent, abstraction rationale, and information that cannot be expressed in code. The claim that "good code is self-documenting" is a myth for anything beyond low-level implementation details.
+
+**Why it works:** Code tells you what the program does, but not why it does it that way, what the design alternatives were, or what assumptions the code makes. Comments capture the designer's mental model -- the abstraction -- which is the most valuable and most perishable information in a system.
+
+**Key insights:**
+- Four types: interface comments, data structure member comments, implementation comments, cross-module comments
+- Interface comments are the most important: they define the abstraction a module presents
+- Write comments first (comment-driven design) to clarify your thinking before writing code
+- "Self-documenting code" works only for low-level what; it fails for why, assumptions, and abstractions
+- Comments should describe what is not obvious -- if the code makes it clear, don't repeat it
+- Maintain comments near the code they describe; update them when the code changes
+- If a comment is hard to write, the design may be too complex
+
+**Code applications:**
+
+| Context | Pattern | Example |
+|---------|---------|---------|
+| **Interface comment** | Describe the abstraction, not the implementation | "Returns the widget closest to the given position, or null if no widgets exist within the threshold distance" |
+| **Data structure comment** | Explain invariants and constraints | "List is sorted by priority descending; ties are broken by insertion order" |
+| **Implementation comment** | Explain why, not what | "// Use binary search here because the list is always sorted and can contain 100k+ items" |
+| **Cross-module comment** | Link related design decisions | "// This timeout must match the retry interval in RetryPolicy.java" |
+| **Comment-driven design** | Write the interface comment before the code | Draft the function's contract and behavior first, then implement |
+
+See: [references/comments-as-design.md](references/comments-as-design.md)
+
+### 6. Strategic vs Tactical Programming
+
+**Core concept:** Tactical programming focuses on getting features working quickly, accumulating complexity with each shortcut. Strategic programming invests 10-20% extra effort in good design, treating every change as an opportunity to improve the system's structure.
+
+**Why it works:** Tactical programming appears faster in the short term but steadily degrades the codebase, making every future change harder. Strategic programming produces a codebase that stays easy to modify over time. The small upfront investment compounds -- systems designed strategically are faster to work with after a few months.
+
+**Key insights:**
+- Tactical tornado: a developer who produces features fast but leaves wreckage behind; often celebrated short-term but destructive long-term
+- Strategic mindset: your primary job is to produce a great design that also happens to work, not working code that happens to have a design
+- The 10-20% investment: spend roughly 10-20% of development time on design improvement
+- Startups need strategic programming most -- early design shortcuts compound into crippling technical debt as the team grows
+- "Move fast and break things" culture (early Facebook) vs design-focused culture (Google) -- Google engineers were more productive on complex systems
+- Every code change is an investment opportunity: leave the code a little better than you found it
+- Refactoring is not a special event -- it is part of every feature's development
+
+**Code applications:**
+
+| Context | Pattern | Example |
+|---------|---------|---------|
+| **Tactical trap** | Resist quick-and-dirty fixes | Don't add a boolean parameter to handle "just this one special case" |
+| **Strategic investment** | Improve structure during feature work | When adding a feature, refactor the module interface if it has become awkward |
+| **Tactical tornado** | Recognize and intervene | A developer who writes 2x the code but creates 3x the maintenance burden |
+| **Startup discipline** | Invest in design from day one | Clean module boundaries and good abstractions even under time pressure |
+| **Incremental improvement** | Fix one design issue per PR | Each pull request improves at least one abstraction or eliminates one piece of complexity |
+| **Design reviews** | Evaluate structure, not just correctness | Code reviews should ask "does this make the system simpler?" not just "does it work?" |
+
+See: [references/strategic-programming.md](references/strategic-programming.md)
+
+## Common Mistakes
+
+| Mistake | Why It Fails | Fix |
+|---------|-------------|-----|
+| **Creating too many small classes** | Classitis adds interfaces without adding depth; each class boundary is cognitive overhead | Merge related shallow classes into deeper modules with simpler interfaces |
+| **Splitting modules by temporal order** | "Read, then process, then write" forces shared knowledge across three modules | Organize around information: group code that shares knowledge into one module |
+| **Exposing implementation in interfaces** | Callers depend on internal details; changes propagate everywhere | Design interfaces around abstractions, not implementations; hide format and protocol details |
+| **Treating comments as optional** | Design intent, assumptions, and abstractions are lost; new developers guess wrong | Write interface comments first; maintain them as the code evolves |
+| **Configuration parameters for everything** | Each parameter pushes a decision to the caller, increasing cognitive load | Determine behavior automatically; provide sensible defaults; minimize required configuration |
+| **Quick-and-dirty tactical fixes** | Each shortcut adds a small amount of complexity; over time the system becomes unworkable | Invest 10-20% extra in good design; treat every change as a design opportunity |
+| **Pass-through methods** | Methods that just delegate to another method add interface without adding depth | Merge the pass-through into the caller or the callee |
+| **Designing for specific use cases** | Special-purpose interfaces accumulate special cases and become bloated | Ask "what is the simplest interface that covers all current needs?" |
+
+## Quick Diagnostic
+
+| Question | If No | Action |
+|----------|-------|--------|
+| Can you describe what each module does in one sentence? | Modules are doing too much or have unclear purpose | Split into modules with coherent, describable responsibilities |
+| Are interfaces simpler than implementations? | Modules are shallow -- they leak complexity outward | Redesign to hide more; merge shallow classes into deeper ones |
+| Can you change a module's implementation without affecting callers? | Information is leaking across module boundaries | Identify leaked knowledge and encapsulate it inside one module |
+| Do interface comments describe the abstraction, not the code? | Design intent is lost; developers will misuse the module | Write comments that explain what the module promises, not how it works |
+| Is design discussion part of code reviews? | Reviews only catch bugs, not complexity growth | Add "does this reduce or increase system complexity?" to review criteria |
+| Does each module hide at least one important design decision? | Modules are organized around code, not around information | Reorganize so each module owns a specific piece of knowledge |
+| Can a new team member understand module boundaries without reading implementations? | Abstractions are not documented or are too leaky | Improve interface comments and simplify interfaces until they are self-evident |
+| Are you spending 10-20% of time on design improvement? | Technical debt is accumulating with every feature | Adopt a strategic mindset; include design improvement in every PR |
+
+## Reference Files
+
+- [complexity-symptoms.md](references/complexity-symptoms.md): Three symptoms of complexity, two causes, measuring complexity, the incremental nature of complexity
+- [deep-modules.md](references/deep-modules.md): Deep vs shallow modules, interface-to-functionality ratio, classitis, designing for depth
+- [information-hiding.md](references/information-hiding.md): Information hiding principle, information leakage red flags, temporal decomposition, decorator pitfalls
+- [general-vs-special.md](references/general-vs-special.md): Somewhat general-purpose approach, pushing complexity down, configuration parameter antipattern
+- [comments-as-design.md](references/comments-as-design.md): Four comment types, comment-driven design, self-documenting code myth, maintaining comments
+- [strategic-programming.md](references/strategic-programming.md): Strategic vs tactical mindset, tactical tornado, investment approach, startup considerations
+
+## Further Reading
+
+This skill is based on John Ousterhout's practical guide to software design. For the complete methodology with detailed examples:
+
+- [*"A Philosophy of Software Design"*](https://www.amazon.com/Philosophy-Software-Design-2nd/dp/173210221X?tag=wondelai00-20) by John Ousterhout (2nd edition)
+
+## About the Author
+
+**John Ousterhout** is the Bosack Lerner Professor of Computer Science at Stanford University. He is the creator of the Tcl scripting language and the Tk toolkit, and co-founded several companies including Electric Cloud and Clustrix. Ousterhout has received numerous awards, including the ACM Software System Award, the UC Berkeley Distinguished Teaching Award, and the USENIX Lifetime Achievement Award. He developed *A Philosophy of Software Design* from his CS 190 course at Stanford, where students work on multi-phase software design projects and learn to recognize and reduce complexity. The book distills decades of experience in building systems software and teaching software design into a concise set of principles that apply across languages, paradigms, and system scales. Now in its second edition, the book has become a widely recommended resource for software engineers seeking to improve their design skills beyond correctness and into clarity.

docq-0.1.0/.claude/skills/software-design-philosophy/references/comments-as-design.md

@@ -0,0 +1,387 @@
+# Comments as Design Documentation
+
+Comments are one of the most debated topics in software engineering. Ousterhout argues that comments are not merely helpful -- they are essential design documentation that captures information that cannot be expressed in code. The belief that "good code is self-documenting" is partially true for implementation details, but dangerously wrong for abstractions, design decisions, and cross-cutting concerns.
+
+
+## Table of Contents
+1. [Why Comments Matter](#why-comments-matter)
+2. [The Four Types of Comments](#the-four-types-of-comments)
+3. [Comment-Driven Design](#comment-driven-design)
+4. [The "Self-Documenting Code" Myth](#the-self-documenting-code-myth)
+5. [Maintaining Comments](#maintaining-comments)
+6. [Comments Anti-Patterns](#comments-anti-patterns)
+7. [Summary](#summary)
+
+---
+
+## Why Comments Matter
+
+Code tells you **what** the program does. Comments tell you:
+- **Why** it does it that way
+- **What** the abstraction promises (the contract)
+- **What** assumptions the code makes
+- **What** alternatives were considered and rejected
+- **What** constraints link this code to other modules
+- **What** is not obvious from reading the code
+
+Without comments, this information exists only in the original developer's head. When that developer moves on, the information is lost. Future developers must reverse-engineer intent from implementation -- an error-prone process that leads to incorrect changes and accumulated complexity.
+
+## The Four Types of Comments
+
+### 1. Interface Comments
+
+**Purpose:** Define the abstraction that a module, class, or function presents to its users.
+
+**This is the most important type of comment.** Interface comments form the contract between a module and its callers. They should describe:
+- What the function/method does (at an abstract level)
+- What each parameter means and its constraints
+- What the return value represents
+- What side effects occur
+- What exceptions can be thrown and under what conditions
+- What the caller must ensure before calling (preconditions)
+- What the caller can assume after the call (postconditions)
+
+**Examples:**
+
+```python
+def find_nearest(target: Point, candidates: list[Point],
+                 max_distance: float = inf) -> Point | None:
+    """Find the candidate point closest to target.
+
+    Returns the nearest point from candidates, or None if no candidate
+    is within max_distance of target. If multiple candidates are
+    equidistant, returns the one that appears first in the list.
+
+    Args:
+        target: The reference point to measure distances from.
+        candidates: Points to search. Must not be empty.
+        max_distance: Maximum Euclidean distance to consider.
+            Points farther than this are ignored. Defaults to
+            infinity (consider all points).
+
+    Returns:
+        The nearest Point, or None if all candidates exceed
+        max_distance.
+
+    Raises:
+        ValueError: If candidates is empty.
+    """
+```
+
+```java
+/**
+ * Acquire a database connection from the pool.
+ *
+ * Blocks until a connection is available or the timeout expires.
+ * The returned connection is guaranteed to be valid (tested with
+ * a lightweight query before returning). The caller MUST close
+ * the connection when done, which returns it to the pool.
+ *
+ * @param timeout maximum time to wait for a connection
+ * @return a valid, open database connection
+ * @throws TimeoutException if no connection is available within timeout
+ * @throws PoolExhaustedException if the pool is permanently full
+ *     (all connections in use and at max capacity)
+ */
+public Connection acquire(Duration timeout)
+```
+
+**Key rules for interface comments:**
+- Describe the abstraction, not the implementation
+- If the comment mentions implementation details (algorithms, data structures, internal variables), it is too detailed
+- A developer should be able to use the module correctly by reading only the interface comment, without reading any implementation code
+- If you cannot write a clear interface comment, the interface may be poorly designed
+
+### 2. Data Structure Member Comments
+
+**Purpose:** Explain the meaning, constraints, and invariants of fields in a class or data structure.
+
+Field names alone rarely convey all the information a developer needs. Comments should clarify:
+- What the field represents (especially if the name is ambiguous)
+- Units and encoding (milliseconds? seconds? UTC? local time?)
+- Valid ranges and boundary conditions
+- Relationships with other fields
+- When the field is set and when it may be null/zero
+
+**Examples:**
+
+```python
+class RetryConfig:
+    # Maximum number of retry attempts before giving up.
+    # Does not count the initial attempt, so total attempts = max_retries + 1.
+    # Set to 0 to disable retries.
+    max_retries: int
+
+    # Base delay between retries in milliseconds.
+    # Actual delay uses exponential backoff: base_delay_ms * 2^attempt.
+    # Jitter of +/- 20% is applied to prevent thundering herd.
+    base_delay_ms: int
+
+    # Maximum delay cap in milliseconds. Exponential backoff will
+    # not exceed this value regardless of attempt number.
+    # Must be >= base_delay_ms.
+    max_delay_ms: int
+```
+
+```java
+class PageCache {
+    // Maps page_id to cached page content. Entries are evicted
+    // in LRU order when the cache exceeds maxEntries. A page
+    // present in this map is guaranteed to match the on-disk
+    // version as of the last sync (see lastSyncTime).
+    private Map<Long, Page> cache;
+
+    // Timestamp of the last cache synchronization with disk,
+    // in epoch milliseconds (UTC). All cache entries are valid
+    // as of this time. Writes after this time may not be reflected.
+    private long lastSyncTime;
+
+    // Upper bound on cache entries. When exceeded, the least
+    // recently accessed entry is evicted before inserting a new one.
+    // Invariant: cache.size() <= maxEntries at all times.
+    private int maxEntries;
+}
+```
+
+### 3. Implementation Comments
+
+**Purpose:** Explain **why** the code does something a particular way, or clarify non-obvious logic.
+
+Implementation comments should not describe **what** the code does -- that should be clear from reading the code itself. They should explain:
+- Why this approach was chosen over alternatives
+- What non-obvious constraint or edge case the code handles
+- What would go wrong if the code were changed in an obvious-seeming way
+- Performance considerations that drove the implementation choice
+
+**Good implementation comments:**
+
+```python
+# Use binary search instead of linear scan because the list is sorted
+# and can contain 100k+ entries. Linear scan caused 200ms latency
+# in production (see incident #4521).
+index = bisect.bisect_left(sorted_entries, target)
+```
+
+```python
+# Process items in reverse order to avoid index invalidation when
+# removing elements. Forward iteration would skip elements after
+# each removal.
+for i in range(len(items) - 1, -1, -1):
+    if should_remove(items[i]):
+        items.pop(i)
+```
+
+```python
+# Intentionally catching broad Exception here because the third-party
+# library can throw undocumented exceptions (observed RuntimeError,
+# ValueError, and OSError in production). We log and continue rather
+# than crash the batch job.
+try:
+    result = third_party_lib.process(data)
+except Exception as e:
+    logger.warning(f"Processing failed for {data.id}: {e}")
+    result = default_result()
+```
+
+**Bad implementation comments (just repeat the code):**
+
+```python
+# Increment counter
+counter += 1
+
+# Check if user is active
+if user.is_active:
+
+# Loop through items
+for item in items:
+
+# Return the result
+return result
+```
+
+These comments add no information. The code already says what it does. Remove them.
+
+### 4. Cross-Module Comments
+
+**Purpose:** Document dependencies and design decisions that span multiple modules.
+
+These are the hardest comments to maintain but often the most critical, because cross-module relationships are the biggest source of unknown unknowns.
+
+**Examples:**
+
+```python
+# This timeout value must be longer than the retry timeout in
+# RetryPolicy (currently 30s with 3 retries = 90s max). If this
+# timeout is shorter, the caller will give up before retries complete.
+# See: src/retry/policy.py:RetryPolicy.MAX_TOTAL_DURATION
+REQUEST_TIMEOUT_SECONDS = 120
+```
+
+```python
+# The field order in this struct must match the binary protocol
+# defined in docs/protocol-v3.md section 4.2. The client parser
+# (client/src/parser.rs) reads fields in this exact order.
+# Changing field order here requires updating both the docs and
+# the client parser.
+class ServerMessage:
+    version: int      # 2 bytes, big-endian
+    message_type: int # 1 byte
+    payload_len: int  # 4 bytes, big-endian
+    payload: bytes    # payload_len bytes
+```
+
+```java
+/**
+ * IMPORTANT: This method is called by the EventBus on a background
+ * thread. It must not access the UI thread directly. Use
+ * Platform.runLater() for any UI updates.
+ *
+ * The EventBus guarantees at-least-once delivery, so this handler
+ * must be idempotent. See EventBus.subscribe() docs for details.
+ */
+public void onOrderCompleted(OrderCompletedEvent event) {
+```
+
+**Best practices for cross-module comments:**
+- Place the comment in the most likely place a developer would look
+- Reference the other module explicitly (file path, class name)
+- Explain what would go wrong if the relationship were violated
+- Consider using a shared constants file for values that must stay in sync
+
+## Comment-Driven Design
+
+**Write the comments before writing the code.**
+
+This is one of Ousterhout's most practical recommendations. The process:
+
+1. **Write the interface comment first:** Before writing any implementation, write the comment that describes what the function/class/module does, what its parameters mean, and what it returns.
+
+2. **Evaluate the design:** If the interface comment is hard to write, unclear, or requires mentioning implementation details, the interface design is probably wrong. Redesign the interface until the comment is clean and simple.
+
+3. **Write the implementation:** With a clear interface comment as your guide, the implementation has a clear target.
+
+4. **Add implementation comments:** As you write code, add comments for any non-obvious decisions.
+
+### Why Comment-Driven Design Works
+
+| Benefit | Explanation |
+|---------|-------------|
+| Forces clear thinking | Writing what something does before how reveals confusion early |
+| Catches bad abstractions | If you can't describe the interface simply, it's too complex |
+| Produces better interfaces | The act of writing clarifies what callers actually need |
+| Comments stay accurate | Written alongside the design, not retrofitted later |
+| Saves time | Avoids implementing a design that turns out to be wrong |
+
+### Example
+
+**Step 1:** Write the interface comment.
+
+```python
+def merge_sorted_streams(*streams: Iterator[T],
+                          key: Callable = None) -> Iterator[T]:
+    """Merge multiple sorted iterators into a single sorted iterator.
+
+    Each input stream must be sorted in ascending order (or by key
+    if provided). The output yields all elements from all streams
+    in globally sorted order. Memory usage is O(num_streams),
+    regardless of stream length.
+
+    Equal elements are yielded in the order their source streams
+    appear in the arguments (stable merge).
+    """
+```
+
+**Step 2:** Evaluate. Is this clear? Can a caller use this without reading the implementation? What about edge cases -- empty streams, single stream, duplicate elements? Add those details if needed.
+
+**Step 3:** Implement. The comment now serves as the specification.
+
+## The "Self-Documenting Code" Myth
+
+The claim that "good code doesn't need comments" contains a kernel of truth but is dangerously incomplete.
+
+### Where Self-Documenting Code Works
+
+Code **can** document itself for low-level implementation details:
+
+```python
+# This is self-documenting -- no comment needed:
+total_price = sum(item.price for item in cart.items)
+is_eligible = user.age >= 18 and user.has_valid_id
+filtered = [x for x in data if x.is_active and x.score > threshold]
+```
+
+Good variable names, clear control flow, and simple expressions make the **what** obvious. Comments that restate this are noise.
+
+### Where Self-Documenting Code Fails
+
+Code **cannot** document:
+
+| Information | Why Code Can't Express It | Example |
+|------------|--------------------------|---------|
+| **Abstractions** | Code shows implementation, not the promise | An interface's contract and guarantees |
+| **Why** | Code shows what happens, not why this approach | Why binary search instead of hash lookup |
+| **Constraints** | Code enforces constraints but doesn't explain them | Why a timeout is set to 120 seconds |
+| **Design alternatives** | Code shows the choice made, not choices rejected | Why we chose polling over webhooks |
+| **Cross-module relationships** | Code in one module can't describe its relationship to another | This timeout must match the retry config |
+| **Performance rationale** | Optimized code is often less readable | Why we denormalized this data structure |
+| **Assumptions** | Code operates on assumptions it cannot state | "This list is always sorted by the caller" |
+
+### The Practical Rule
+
+**Use self-documenting code for the "what" (implementation). Use comments for the "why" (design decisions), the "what" at a higher level (abstractions/interfaces), and the "beware" (non-obvious constraints and relationships).**
+
+## Maintaining Comments
+
+Comments that are wrong are worse than no comments. Here are strategies for keeping them accurate:
+
+### 1. Place Comments Near the Code
+
+The closer a comment is to the code it describes, the more likely it will be updated when the code changes. Interface comments in the function signature are better than comments in a separate documentation file.
+
+### 2. Avoid Duplicating Information
+
+If the same information is stated in a comment and enforced in code, one will eventually become stale. State each fact once.
+
+```python
+# Bad: duplicates the type annotation
+# max_retries is an integer representing the maximum number of retries
+max_retries: int  # The type already says it's an int
+
+# Good: adds information not in the code
+# Set to 0 to disable retries. Values > 10 are capped at 10 to prevent
+# excessive load on the downstream service during outages.
+max_retries: int
+```
+
+### 3. Update Comments in the Same Commit
+
+Make it a code review norm: if you change a function's behavior, you must update its interface comment in the same commit. Stale comments are a code review finding.
+
+### 4. Use Comments as a Design Smell Detector
+
+If a comment is hard to write, the code may be too complex. If a comment needs to be very long, the interface may be doing too much. If a comment keeps going out of date, the module's boundaries may be wrong. Difficult comments are a signal, not just a chore.
+
+### 5. Treat Comment Quality as a Review Criterion
+
+In code reviews, evaluate comments alongside code:
+- Are interface comments complete and accurate?
+- Do implementation comments explain why, not what?
+- Are cross-module comments present where needed?
+- Are there missing comments on non-obvious code?
+
+## Comments Anti-Patterns
+
+| Anti-Pattern | Problem | Fix |
+|-------------|---------|-----|
+| **Comment repeats the code** | Adds noise, no information | Delete it; let the code speak for implementation details |
+| **Comment describes what, not why** | Misses the valuable information | Rewrite to explain the reasoning or design decision |
+| **Comment on every line** | Obscures code, hard to maintain | Comment only non-obvious sections; trust clear code |
+| **TODO without context** | "TODO: fix this" is useless months later | Include the issue number, the problem, and the fix direction |
+| **Commented-out code** | Dead code that confuses readers | Delete it; version control preserves history |
+| **Banner comments** | `/////// SECTION ///////` adds structure without information | Use meaningful function/class boundaries instead |
+| **Apology comments** | "Sorry, this is a hack" acknowledges but doesn't fix | Fix the hack or add context on why it is necessary and when it can be fixed |
+| **Stale comments** | Describe behavior that no longer exists | Update or remove in the same commit as the code change |
+
+## Summary
+
+Comments are not a sign of bad code. They are design documentation that captures the most valuable and perishable information in a system: the designer's intent, the abstraction's contract, and the non-obvious relationships between components. Write interface comments first, maintain them alongside code, and use them as a tool for thinking clearly about design.