• 0 Vote(s) - 0 Average
  • 1
  • 2
  • 3
  • 4
  • 5
Comments and explanations - how to do it better?

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 :-)


Messages In This Thread
RE: Comments and explanations - how to do it better? - by PaulD - 01-14-2016, 05:18 AM

Digg   Delicious   Reddit   Facebook   Twitter   StumbleUpon  

  Theme © 2014 iAndrew  
Powered By MyBB, © 2002-2021 MyBB Group.