[barrkel]

OK. But the algorithm is over a 1000 lines split up into perhaps 50 20-line functions, and it's mysterious how the whole works by looking at the parts.

I have one particular piece of code, that I wrote, in mind. It was to implement anonymous methods in the Delphi compiler. Given an AST for a method from the parser, it had to rewrite the tree to turn captured local variable references into field accesses on a heap-allocated stack frame, turn anonymous methods into methods on this heap-allocated stack frame, and all while minimizing the number of passes over the tree. And this has to work recursively, which adds a surprising number of wrinkles about the ordering in which you can do things.

So for example any given pass may be building up accounting data needed by later passes. This is somewhat mysterious, because it seems like busywork; and why is it doing this here? Why not fold one pass into another? Why not move work between passes? Well, the subtle ordering problems are not clear at all when you're looking at things at the function level. You can only understand the pieces when you already understand the whole.

And this is why there is a very long comment block describing how this stuff works. Because figuring it out by reading the code is too expensive.

(That ~1000 lines of code took perhaps 4 months to write; having to integrate with rest of a large complex codebase adds countless more wrinkles.)