In this example I'd have to agree. It's more on a case by case basis for this then. Does the comment add any value to the end user (developer) or is it just adding to the signal to noise ratio? Having comments that provide no value to the user probably should be cleaned out for clarity. How that gets done, other than someone manually going through and evaluating each comment, I don't know. But I would have no problem if those types of comments are removed. I just don't want to see existing "helpful" comments being removed or relocated to a different external file. It would just add grief to maintenance being that there is now more than one place to update. Change code in Class.as and then open other doc to change comment/description. I'd still rather update the comment in the Class file and let ASDoc create the other documents via export.
Definitely not an easy nut to crack with so many classes and thousands of lines of code to go through. Neil -----Original Message----- From: Carol Frampton [mailto:cfram...@adobe.com] Sent: February-16-12 12:17 PM To: flex-dev@incubator.apache.org Subject: Re: asdoc comments for flash player and SDK version numbers Some of this code has existed a long time. We no longer use @private except if you want to keep a public var or method hidden from asdocs. Most people do not doc obvious private variables or they may just use a one line // comment. /** * Sets the title. * */ public function set title(value:String):void {...} is just silly. The comment adds nothing. UIComponent is not a good one to pick apart since it has been around for so long. Carol On 2/16/12 1 :40PM, "Omar Gonzalez" <omarg.develo...@gmail.com> wrote: >On Thu, Feb 16, 2012 at 10:22 AM, Neil Madsen ><li...@cranialinteractive.com>wrote: > >> 100% agreement here. >> Having had to just port an incredibly complex military application I >>wrote years ago I can tell you I was sooooo happy that I took the >>time back then to write as many comments as I did in the code. I even >>found myself wishing I had exanded on the comments to make it even >>easier to understand what some of the methods were doing and how >>they were intertwined. So I just don't understand the reasoning for >>wanting to remove the comments. They aren't compiled into the final >>output and they make it easy to understand what's going on in the >>class with a quick overview. They appear when hovering over the >>method or property in your own class so you can see what the >>parameters are etc. I really see zero downside of keeping them in and >>I know it will frustrate the hell out of me if I have to go to a >>browser or open other files to see what a method or property is >>supposed to do. >> >> If it ain't broke..... >> >> Just my 2 cents. >> >> Neil >> >> >I don't think anyone is arguing about the usefulness of code comments. >However there are a lot, and I mean a lot, of comments that are simply >noise. Take for example: > >/** >* @private >*/ > >/** >* Sets the title. >* >*/ >public function set title(value:String):void {...} > >/** >* @Constructor >*/ > >All this kind of crap just makes it more difficult to read through code >and provides little to no deeper of an understanding. I prefer, instead >of exerting tons of effort trying to write prolific documentation in >source code, to exert much more time in making sure my code in legible, >cleanly formatted, and as readable as possible. That said, we are >building a framework with an API that will be used by thousands and >thousands of people, the ASDoc comment blocks are necessary to generate >the API documentation with ASDoc that all developers need and require. >What I'm curious about is if we can find a solution that provides the >best of both worlds. Perhaps this solution doesn't exist, but its worth >talking about. > >Take this from UIComponent: >/** >* @private >* Holds the last recorded value of the x property. >* Used in dispatching a MoveEvent. >*/ >private var oldX:Number = 0; > > >This could be written as: > >private var lastMoveEventValueForX:Number = 0; > >I just turned 6 lines in the source code to 1 and it still expresses >exactly what its intention is. That's an 85% reduction in code if you >like to play the numbers game. There are 14000+ lines of code in >UIComponent, I wonder how much can be removed from that by simply >naming variables better and resulting in much cleaner code. I would >rather read the variable name and immediately know what the variable is >for than to read 'oldX'... old X of what? When is this used? I have to >now leave the portion of the code I'm in to read the definition at the >top of the class, 14000 lines away, or try to trigger a tooltip in my >IDE to read what that variable is all about. > >There are obviously cases where comments are just absolutely necessary, >but I just wanted to bring up some of my reasoning. I don't have a >solution for meeting both the needs we have to generate ASDoc >documentation while keeping the noise from comments in the source code >low. > >-omar
