Skip to main content

Featured

The Docstring Coverage Gate Is the Product: What I Verified in AI Doc Generator

The Docstring Coverage Gate Is the Product: What I Verified in AI Doc Generator Documentation debt never announces itself. It shows up as the three hours you lose reading a function called process_data2 , or as the README that documents an argument the code stopped accepting two refactors ago. Every team knows the number that matters is documentation coverage, and almost nobody has a cheap way to measure it, let alone gate a merge on it. That is the specific pain I went looking for a tool to solve, and it is how I ended up testing AI Doc Generator — a $49 single-file Python CLI that scans a codebase for undocumented functions and classes. This post is what I actually measured in the bundle, on my machine, from a clean copy. Including the parts that don't work. Yes, it is a product I sell, and this article says so plainly rather than dressing up as a neutral review. The real problem: coverage is invisible until it is a crisis Ask a team what fraction of its public functions...

The First Computer Bug Was a Real Moth

Somewhere in the archives of an early American computer lab, there is a page of a logbook with a moth taped to it. Not a photograph of a moth. The moth itself, pressed flat, with a note beside it explaining that the insect had been found inside a relay and was the cause of a fault. That page is the reason people say the first computer bug was a real bug. It is also why the phrase gets repeated slightly wrong, because the machine was not a modern computer in the sense most people mean, and the word "bug" did not start with that moth. This post walks through what the video shows, what the documented incident involved, and what to take away from a story that is part engineering history and part language history.

Watch the short: The First Computer Bug Was a Real Moth

A quick science explainer from our YouTube channel — full playlist on the channel page.

The short version

A relay-based computer at Harvard, the Mark II, was misbehaving. When the operators opened the machine to look for the fault, they found a moth trapped in one of the mechanical switches. They removed it, taped it into the machine's logbook, and noted it as the first actual case of a bug being found in the system. The joke landed because the fault really was caused by an insect, and because the word for a mysterious malfunction was already "bug".

Two things follow. First, the story is genuine and documented, not a piece of internet folklore invented later. Second, the moth did not invent the word. Engineers had been calling faults "bugs" long before anyone found one with six legs. What the moth did was turn a metaphor into a literal object, which is why the story has outlived almost everything else about that machine.

What the video shows

The short is compact and carries one idea: the earliest documented "computer bug" was an insect, physically removed from the hardware and preserved in a logbook. It does not try to be a documentary about the Mark II, and it does not walk through the machine's architecture. Its job is to deliver a single, memorable fact in under a minute and let the viewer go looking for more.

For transparency, the footage is stock and public-domain style imagery and the narration is an AI voice. That is worth saying plainly, because the appeal of the story is that it is documented, and a viewer should know the video is an explainer assembled around a historical artifact rather than a recording made in the room.

What the machine actually was

The Mark II was an electromechanical computer, which means its logic ran through physical switches rather than transistors. Relays are switches operated by electromagnets, and they click. That matters for the story, because a relay is a mechanical device with an air gap and moving contacts, and an air gap is a place where a small object can sit and stop a contact from closing.

That is the whole mechanism of the incident. Nothing exotic happened. A warm, sheltered, enclosed space full of gently clicking metal is a reasonable place for an insect to end up, and a switch that cannot close is a fault the operators would notice immediately. The machine was not mysteriously cursed. It had something stuck in it, the way a stuck key on a keyboard has something stuck in it.

This is also why the story is more than a pun. Anyone who has debugged hardware has looked for a logical error and found a physical one instead: a loose connector, a speck of dust on a contact, a cable seated a millimetre short. The moth is the ancestor of all those afternoons.

Why the logbook page is the real artifact

The reason this story can be told at all is that the team wrote it down in the machine's logbook and kept the specimen. In an engineering lab, the logbook is where faults, fixes and observations get recorded so the next shift does not repeat the same diagnosis. Taping the moth to the page was a joke, but it was a joke made inside a formal record, which is what turned an annoyance into a piece of history.

That detail is the most useful part of the story for anyone working with systems today. The moth would be forgotten; the page is not. A fault written down with what was found and what was done becomes knowledge, and the same fault solved silently becomes a rumour.

The word "bug" is older than the moth

Here is where the popular version of the story drifts. People often describe the moth as the moment the word "bug" was invented for a technical fault. It was not. Engineers and inventors had used "bug" to mean a defect or a persistent irritation in a machine for decades before the Mark II existed, and the usage shows up in the writing of people working on electrical and mechanical systems in the era before electronic computers.

So the honest summary is narrower and better: the Mark II moth is one of the earliest well-documented cases of a real insect found as the cause of a fault in computing hardware, and the logbook note fixed the story in place. The word was already waiting. The moth just gave it a body.

The story is also frequently attached to the name of a prominent figure in early computing, which is part of why it spread so widely. We are not building the post around that attribution, because the logbook entry is the part of the record doing the work. If you go looking you will find the tale told with varying emphasis, and occasionally with details that differ. The moth, the machine and the note are the stable parts.

Why the story still gets told

Most early computing anecdotes age badly, because the machinery they describe is so remote that the joke needs a diagram. This one survives for three reasons.

  • It is physical. Everyone has had a fault with a physical cause. The moth needs no explanation of what a relay is.
  • It is self-documenting. The punchline and the evidence are the same object. You do not have to trust a retelling.
  • It inverts an expectation. We say "bug" so casually that we forget it is a metaphor. Finding a literal one is the kind of coincidence that makes a fact stick.

There is also a quieter reason. The earliest computing failures were not abstractions: they were things you could hold, remove with tweezers and tape to a page. Modern debugging is mostly invisible, a stack trace or a log line, and the moth corrects the idea that faults are purely conceptual.

How to use this when you are the one debugging

The story suggests a simple discipline.

  • Check the physical layer before the logical one. Power, cabling, seating, obstruction, dust. Unglamorous, and it resolves a surprising share of problems.
  • Write down what you found, not just what you fixed. The finding saves the next person time.
  • Do not let a good story substitute for a diagnosis. "It was a bug" is a category, not a cause. The story works because someone opened the machine and identified the moth.

None of that requires believing the moth invented the word. It only requires noticing that the fault had a physical cause and that somebody recorded it.

Common questions

Was the first computer bug really a moth?

Yes, in the documented sense. An actual moth was found causing a fault in a relay of the Harvard Mark II, and it was preserved in the machine's logbook with a note to that effect.

Did that incident create the word "bug"?

No. The term was already in use for mechanical and electrical faults before that. The moth is the earliest well-documented case of a literal insect causing a computer fault, not the origin of the vocabulary.

Was the machine a computer?

It was an electromechanical computer built from relays. It computed, but through physical switches clicking rather than through electronic logic, which is precisely why an insect could stop it.

Why does the logbook matter more than the moth?

Because the record is what makes the story verifiable and repeatable. Without the note, the same event would be a lab anecdote nobody could check.

How we made the short

The video uses stock imagery and an AI-generated narration, and the explanation was written from the documented logbook incident and general computing history rather than from a technical paper. We kept the claims general: no dates, no relay counts, no invented quotes. If something here goes beyond what the record supports, tell us below and we will correct it.

Who this is for / bottom line

This explainer is for curious viewers, students, teachers, and anyone who has used the word "bug" without wondering where it came from. It is not a history of the Mark II, and it is not a guide to relay logic. The bottom line: a real moth really was found inside a relay computer, really was taped into the logbook, and really was the cause of the fault. The word "bug" was already older than the moth. What the moth gave us was proof that a fault can be a physical thing you can hold in your hand, and a reminder that the person who writes down what they found is the one who makes it history.

Questions or corrections: nandminc2020@gmail.com.

Comments