Sixteen wrong comments, one shape: rot is a category, not a fog

A developer working on Coffer, a file store that encrypts everything in the browser before it uploads ^[1], read all of the roughly 2,000 comment lines in the codebase against the code they claim to describe, in one pass, and found sixteen wrong ^[2][3]. All sixteen failed the same way: every wrong comment described something outside its own file, and not one comment sitting directly above the code it documents was wrong ^[11].

The denominators matter. The codebase carries about 2,000 comment lines against 19,500 lines of C# and TypeScript, roughly one line in ten, in around 670 comment blocks across 225 files ^[2]. The author reports the defect rate as about 2.4% and says it was lower than he feared ^[4]. That figure is sixteen bad blocks out of 670 ^[5]; measured per comment line it is about 0.8% ^[6], because blocks average about three lines and files average about three blocks ^[7].

The four examples given show the failure has range. A deploy script's header comment described its own sync step 240 lines below and claimed the script deletes removed files with `rsync --delete`, while the body of the same script explains at length that `rsync --delete` is exactly what must not happen there, and diffs a per-deploy manifest so it can only remove what it previously put there ^[12]. A server-side `Plan.cs` said multi-GB uploads would not complete in-browser until chunked encryption landed; chunked encryption had landed, and a 4.8 GB upload had been verified byte-exact months earlier ^[13]. A client-side `VaultPage.tsx` called the server's cleanup job "the daily sweep"; the sweeper runs hourly and reclaims sessions older than 24 hours ^[14]. All sixteen fit one of three species, and per the author every one of them was true when it was written ^[16].

The mechanism he proposes is boring, which is a point in its favour. A comment about local code gets checked constantly, by everyone who edits the line beneath it, inside the diff where the change lives; a comment about remote code is checked by nobody, because the change that falsifies it happens in a file where the comment is not visible ^[19]. His worked example: adding a second sign-in provider touched the auth controller, the startup configuration and a button component, and did not touch the account page, the user manager's logging comment, or two test files ^[17]. On merge, six comments in files that change never opened became false, because each said "Google" where the code underneath had become "any external provider". No diff showed it, no test failed, and `git blame` still points correctly at the commit that wrote them months earlier ^[18].

Two caveats sit inside the audit itself. An AI coding agent did the reading, with every flagged defect confirmed against the referenced source before anything was edited ^[8], and two of the sixteen could not be settled in the editor at all: one required computing a probability, one required checking the live production host ^[9]. That second one is the limit of "detectable". A comment in `Program.cs` justified a retry around database migration with a hardware fault on the production host that made the clock jump at boot; the fault had since been fixed, and nothing in the repository could have revealed that ^[15]. The whole set was cleared in six commits ^[10].

Worth watching whether the cross-file rule holds in a codebase with many authors rather than one. If it does, the audit set is cheap to define: any comment naming a file, a service, a schedule or an identifier that does not appear in the same file. In this codebase that set contained every defect ^[11], and the ones grounded in facts outside the repository stayed invisible to it ^[15].