As a software engineer who has sometimes specifically specialized in handling dragons, I always try to leave (sometimes voluminous) comments about why a thing was handled that way when it's not obvious to a surface reading.

Good practice in general but particularly so when you find a heisenbug that must be exterminated.