Comments and explanations - how to do it better?

@includebeer
Yes I agree, it is either as I go along or not at all.

In a new project I am starting today I am trying really hard to comment as I go, with a view to my future self re-working the code for whatever reason.

I had some reworking to do earlier today of an older site and quite honestly it was driving me up the wall. A few explanatory comments would have helped a lot. It is not a problem in simple sites, my comments are sufficient and minimal. It is when you have a controller that is actually doing tons of complex jobs, in the middle of a complex app that has multiple user types, multiple permissions, multiple status settings and conditionals etc etc.

So in conclusion I am now trying out a rule of 'if it is a complex method that does not lend itself to easy self-explanation, then I add a comment summary at the bottom, as if it was documentation. So far it seems to be working well but I will only be able to tell when I come back to it in six months time. After all, most methods are completely simple and self explanatory, and writing documentation is just simply too much of a massive task to tack on to the end of a project.

Fingers crossed :-)

Paul.