Instead of a comment informing a user how something works (or how something does not work), write a test demonstrating and documenting its use. The test will n

Instead of a comment informing a user how something works (or how something does not work), write a test demonstrating and documenting its use. The test will not forget, and has a docstring explaining what and why. But crucially, it is automated, and does not rely on mistake-prone humans to check (as is the case of a comment).