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. |
Welcome Guest, Not a member yet? Register Sign In |