complete-code-no-stubs
verifiedac0e29d8-10f3-4064-9a4e-ef88f472dabb
Write complete, runnable code with no TODO, ..., pass, or placeholder markers — every path is filled in. Use whenever generating code so you never hand back a skeleton.
Metadata
Skill file
# Complete Code, No Stubs
Use whenever you generate code — the deliverable is a complete, runnable
implementation with every branch filled in. Never hand back a skeleton that the
receiver has to "finish up."
## 1. The anti-pattern catalog
These markers mean "this file is not done." None of them may ship:
| Marker | Why it is a bug |
|---|---|
| `# ... rest of processing` | A comment promising code that does not exist. |
| `pass # TODO: implement` | A function that silently does nothing. |
| `raise NotImplementedError` | A function that crashes when called. |
| `# TODO`, `# FIXME`, `# XXX` | Deferred work with no owner or due date. |
| `return None` "for now" | A silent wrong answer, worse than a crash. |
| `...` (Ellipsis) as a body | A placeholder the reader must decode. |
## 2. Substituting real behavior for every branch
Before calling a file "done", walk every branch and confirm each returns real
behavior — including error paths:
```python
# INCOMPLETE — the error path is a stub
def get_user(user_id: str) -> User | None:
if user_id:
return db.fetch_user(user_id)
else:
pass # TODO: handle empty id
# COMPLETE — every path has real behavior
def get_user(user_id: str) -> User:
if not user_id:
raise ValueError("user_id is required")
user = db.fetch_user(user_id)
if user is None:
raise UserNotFoundError(user_id)
return user
```
The error path is not optional. Code that handles the happy path and stubs the
failure path is incomplete — failure is exactly where bugs surface in production.
## 3. When a genuine TODO is unavoidable
Sometimes you legitimately cannot fill in a path (blocked on a missing dependency,
an undecided business rule). Then do **one** of:
1. **Leave it out of the deliverable** — narrow the scope so the incomplete path
is not part of what you hand back.
2. **Link a ticket** — write `# TODO(#1234): implement retry once the API client
lands` with a real issue id, owner, and reason.
A TODO with a ticket and a reason is acceptable. A bare `# TODO` is not.
## 4. The "no syntax error is not complete" rule
Do not confuse "compiles / imports cleanly" with "done." A file can parse
perfectly and still be full of stubs. Run the code — exercise at least one
happy path and one error path — before declaring it complete.
```bash
# A file that parses but does nothing when run is still incomplete
python -m py_compile module.py # parses -> NOT sufficient proof of completion
python -c "import module; print(module.get_user(''))" # run it -> real proof
```
## 5. Worked example: completing a half-written function
You receive this and are asked to "finish it":
```python
def charge_user(user_id: int, amount_cents: int) -> str:
if amount_cents <= 0:
return "error" # stringly error, no context
# TODO: actually charge the card
pass
```
Complete it so every path returns real behavior:
```python
def charge_user(user_id: int, amount_cents: int) -> ChargeResult:
if amount_cents <= 0:
raise InvalidAmountError(amount_cents)
user = db.get_user(user_id)
if user is None:
raise UserNotFoundError(user_id)
charge = gateway.charge(user.payment_token, amount_cents)
return ChargeResult(charge.id, charge.status)
```
Every branch — bad amount, missing user, successful charge — now returns a real,
typed result. Nothing is a placeholder.
## 6. The review-time check for stubs
When reviewing your own or others' code, run a mechanical sweep for incompleteness:
```bash
rg -n 'pass\s*(#.*)?$|\.\.\.\s*$|NotImplemented|TODO|FIXME|placeholder|stub|not implemented|rest of' src/ tests/
```
Then classify each hit:
| Hit | Verdict |
|---|---|
| `pass` in a real function body | Incomplete — must be filled |
| `...` as a body | Incomplete — must be filled |
| `NotImplementedError` shipped | Incomplete unless behind a documented "unsupported" contract |
| `TODO` with ticket id + reason | Acceptable |
| `TODO` bare | Incomplete |
If the sweep returns anything you cannot justify, the file is not done.
## Guardrails
- Do **not** ship `pass`, `...`, `raise NotImplementedError`, `# TODO`, or `# FIXME`
in a finished file.
- Do **not** leave `return None` as a placeholder for "I'll implement it later."
- Do **not** return a function that is half-wired (declared but never called by
anything that exercises it).
- Do **not** claim "done" for a file you have not run at least once.
- If a TODO is unavoidable, attach a ticket id and a reason, or exclude that path
from scope.
## Pitfalls
- **"No syntax error = complete"** — a file that imports cleanly but contains a
`pass` body is still a stub.
- **Half-wired functions** — you wrote `process_order()` and `finalize_order()` but
never connected them; the feature does not actually work end-to-end.
- **Silent stubs** — `except Exception: pass` is a stub masquerading as error
handling (see defensive-error-handling).
- **TODO spam** — dozens of `# TODO` markers with no ticket and no owner, so nobody
ever follows up.
- **Comment-as-stub** — `# rest of processing` where real code should be.
## Verify / Checklist
- [ ] No `pass`, `...`, `raise NotImplementedError`, `# TODO`, or `# FIXME` in the delivered file(s).
- [ ] Every function has a real body and every branch returns real behavior.
- [ ] Error paths are implemented, not stubbed or silently swallowed.
- [ ] The code was run (not just compiled/imported) and produced expected output.
- [ ] Any remaining TODO has a ticket id and a reason, or the path was descoped.
- [ ] `grep -rnE 'TODO|FIXME|NotImplemented|pass$|\.\.\.'` returns nothing unexpected in the deliverable.Attached files
No attached files.