flex-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Carol Frampton <cfram...@adobe.com>
Subject Re: asdoc comments for flash player and SDK version numbers
Date Thu, 16 Feb 2012 19:17:05 GMT
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.


On 2/16/12 1 :40PM, "Omar Gonzalez" <omarg.developer@gmail.com> wrote:

>On Thu, Feb 16, 2012 at 10:22 AM, Neil Madsen
>> 100% agreement here.
>> Having had to just port an incredibly complex military application I
>> years ago I can tell you I was sooooo happy that I took the time back
>> to write as many comments as I did in the code. I even found myself
>> 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
>> going on in the class with a quick overview. They appear when hovering
>> the method or property in your own class so you can see what the
>> are etc. I really see zero downside of keeping them in and I know it
>> 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
>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
>in to read the definition at the top of the class, 14000 lines away, or
>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,
>I just wanted to bring up some of my reasoning. I don't have a solution
>meeting both the needs we have to generate ASDoc documentation while
>keeping the noise from comments in the source code low.

View raw message