Comments and explanations - how to do it better?

@InsiteFX, I also like the todo features of PhpStorm. For those who don't know, it has nice comment highlighting and you have an overview of all todo's in your entire project.

I try to write very short oneliners for comments as I code along. At the end of the day if I have a few minutes to spare I spend reviewing the code I did that day and add some more comments if needed (or add a todo comment if I believe some refactoring could be usefull for example). But truthfully it's hard to follow this...

If I move some code from a controller to lets say some trigger event inside a model I always leave a small comment referencing this change at the original place. It can help you save some time later on figuring this out if you forgot you refactered this peace of code.

Another thing I would recommend is to review your own code periodically.