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
