This comes with a huge caveat: You must explain it in enough detail for anyone encountering it to understand why it's dangerous and what they should be doing in

This comes with a huge caveat: You must explain it in enough detail for anyone encountering it to understand why it's dangerous and what they should be doing instead, if at all possible. The documentation must at the very least be where the name is defined. "But why?!" is exactly the wrong thing for a developer in a hurry to be thinking.