Your go/ast codemod rewrites 400 files, but the printed output drops some comments and attaches others to the wrong declaration. Why, and how do you fix it?

## Why comments float Go's grammar has no place for comments, so the parser cannot make them children of anything. With `parser.ParseComments`, the parser puts **every** comment group into `ast.File.Comments`, a flat slice ordered by position. Separately, when a comment group sits immediately before a declaration, spec or struct field, the parser also stores a pointer to it in that node's `Doc` field (and trailing same-line comments in a `Comment` field). Those pointers are a convenience view; the authoritative list is `File.Comments`. The printer works off the authoritative list. `go/format.Node(w, fset, file)` walks the tree emitting nodes, and in parallel walks `File.Comments`, flushing each group at the point where its recorded `token.Pos` falls relative to the positions of the nodes being emitted. Comment placement is therefore **a function of positions, not of tree structure**. ## What the rewrite breaks Once you start editing, positions stop describing the tree: - A declaration you **move** keeps the positions it was parsed with, so relative order by position no longer matches order in `Decls`. The printer flushes a comment group when it passes the group's position, which may now be next to something else entirely. - A node you **synthesise** has `token.NoPos` everywhere. It sorts before everything, so comments cluster oddly around it. - A node you **delete** takes no comments with it; the group that documented it is still in `File.Comments` and gets flushed against whatever node now occupies that stretch of the position line. - Comments whose positions fall outside anything the printer emits can be **dropped silently**. The symptom in review is exactly what the question describes: a doc comment sitting above the wrong function, a licence header duplicated or lost, and — the second-order damage — unrelated lines reformatted because reprinting the whole file re-canonicalises everything, including alignment and blank-line grouping the author chose. ## Fix one: maintain the association explicitly `go/ast` ships `ast.CommentMap` for exactly this. Build it **before** editing, while positions still describe the tree: ```go cmap := ast.NewCommentMap(fset, file, file.Comments) ``` The map is keyed by node, so it survives moving a node around: the association is now structural rather than positional. After the edits, project it back: ```go file.Comments = cmap.Filter(file).Comments() ``` `Filter` drops entries whose node is no longer in the tree — that is what stops a deleted function's doc comment reappearing — and `Comments()` flattens what remains back into the sorted slice the printer wants. You can also move a comment deliberately by re-keying it: `cmap[newNode] = cmap[oldNode]; delete(cmap, oldNode)`. For printing a single node with its comments, `printer.CommentedNode{Node: n, Comments: groups}` is the form the printer understands. This works, but it is fiddly, and it does not address the reformatting of untouched lines. ## Fix two: never reprint the file For a large mechanical change the better answer is usually to treat the AST as a **finder**, not a rewriter. Parse to locate the exact byte ranges you want to change, then splice the original source: ```go start := fset.Position(node.Pos()).Offset end := fset.Position(node.End()).Offset ``` Apply the edits in **descending offset order** so earlier offsets stay valid, and write the result. Everything you did not touch is byte-identical — comments included, because you never asked the printer to place them. Run `format.Source` on the result only if your replacement text could disturb formatting, and accept that doing so re-canonicalises the file. The reason this matters is the review, not the machine. A 400-file diff that changes only the lines it meant to change can be read; the same change wrapped in a whole-repo reformat cannot, and reviewers rubber-stamp it. If a reformat is genuinely wanted, land it as a **separate, mechanical commit** so each half is reviewable on its own. ## Diagnosing it when it has already happened - Print positions as you go: `fset.Position(n.Pos())` for every node you touch, mapped back to `file:line:col`, tells you immediately when a node you moved is still claiming its old coordinates. - Dump the tree with `ast.Print(fset, file)` to see which `Doc` fields are populated and where each group sits. - Diff a single file both ways — reprinted versus spliced — on a file you know well before running across the repo. The pilot file is where you discover the licence header moved. - Re-run the tool on its own output. A correct codemod is idempotent; if the second run produces another diff, comment or formatting handling is wrong. ## The rule to remember Comments are attached by coordinates, and every edit invalidates coordinates. Either you take over the association explicitly with a `CommentMap` before you edit, or you avoid the printer altogether and let the original bytes carry the comments through untouched.