I have certainly seen my fair share of bad comments. commented out comments. blocks of code which have been commented out and disabled but the comments are still there for that disabled code and have not been updated. comments for code which no longer exists.
but it all comes down to the same thing really, poor documentation and commenting, regardless of the end result. I tend to put very simple comments in code, for anything major or for apps that were likley to be maintained by someone else I wrote documentation and refer to that in the code using in page header comments. On Thu, Mar 1, 2012 at 4:15 PM, Raymond Camden <raymondcam...@gmail.com>wrote: > > Mike, some arguments are comments are: > > 1) Repeats what's already obvious. For example: > > <!--- Loops over my crap ---> > <cfloop index="x" from="1" to="#arrayLen(crap)#"> > > 2) Easy to become outdated. > For example, a comment that says something like, "This hunts for bears > using a shotgun" whereas the code was modified to hunt for bears using > blunt toothpicks. Maybe another developer made that change and simply > didn't feel like updating the code. > > The book, Clean Code > ( > http://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882 > ), > has a whole chapter on it. > > Now to be clear, I don't actually agree with all the points. I'm "Pro > Comment", just sharing some reasons why. > > On Thu, Mar 1, 2012 at 9:34 AM, Mike Kear <afpwebwo...@gmail.com> wrote: > > > > I dont understand what's the problem with comments anyway. So what if > we > > have comments peppered through the code? Do they slow down processing > in > > any significant way? Yes, they cause the files to be somewhat larger, > > but if all that means is a bit more disk space gets used, so what? If > > they reduce maintenance cost because its quicker for other developers to > > maintain the code later on, that must surely more than offset any > overhead > > due to the existence of comments. > > > > -- > =========================================================================== > Raymond Camden, Adobe Developer Evangelist > > Email : raymondcam...@gmail.com > Blog : www.raymondcamden.com > Twitter: cfj > > ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~| Order the Adobe Coldfusion Anthology now! http://www.amazon.com/Adobe-Coldfusion-Anthology/dp/1430272155/?tag=houseoffusion Archive: http://www.houseoffusion.com/groups/cf-talk/message.cfm/messageid:350186 Subscription: http://www.houseoffusion.com/groups/cf-talk/subscribe.cfm Unsubscribe: http://www.houseoffusion.com/groups/cf-talk/unsubscribe.cfm
