[randomdata]

I think inline comments are fine for when you are doing something really weird (for, say, performance reasons) that needs explanation, but if you want to document the why of the entire codebase, I feel the test suite is a better place for that.

Not only can you explain the why and demonstrate usage in a logical manner, but you get some consistency checks from your documentation for free.