[TeMPOraL]

> Kind of the whole problem is when there are weird corner cases going on that straddle function boundaries.

If the problem has "hub and spokes" topology, i.e. it's relevant to multiple places in code that all reference a single location, put a comment describing the issue in that single location, and everywhere else put a comment with a reference. //Warning. See comment in [that location].

If there's no single best place for the detailed comment, put it in some design notes file, and put a comment with a reference to that file in all the affected places.

DRY can, and should be, applied to comments as well.

[emn13]

Centralized comment references sounds like a good+simple idea - I'll try to remember it, and hope I never have to of course ;-).

[TeMPOraL]

Yeah, references to a centralized document is such an obvious thing... once you read about it. It's another thing I recently picked up from Ousterhout's book, and looking back, I can now see the places in past codebases where I wish I thought of that myself.