That's a good point indeed. For this particular case I like to put in a comment next to the weird thing that seems out of place. It can be a short summary and

That's a good point indeed. For this particular case I like to put in a comment next to the weird thing that seems out of place. It can be a short summary and the link to a specific ticket for example. Also, tests. Edit: actually id like to emphasize the need for tests. One must be able to refactor code without fearing to break undocumented requirements.