Mailing-List: contact flex-dev-help@incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: flex-dev@incubator.apache.org
Received-SPF: pass (nike.apache.org: domain of
 SRS0=/k24fv=A2=cranialinteractive.com=lists@eigbox.net designates
 66.96.185.20 as permitted sender)
Reply-To: <lists@cranialinteractive.com>
From: "Neil Madsen" <lists@cranialinteractive.com>
To: <flex-dev@incubator.apache.org>
References: <FA124D97-2584-41D4-A96D-F93293F0F8B4@classsoftware.com>
 <1329381498.4139.10.camel@lapsang>
 <CAEFz_vvbv5Kjqk2MQAS0gqR5=D3=2qn2p_Ow+04-UUbpPhRw1Q@mail.gmail.com>
 <4F3D1D16.7080205@dot-com-it.com>
In-Reply-To: <4F3D1D16.7080205@dot-com-it.com>
Subject: RE: asdoc comments for flash player and SDK version numbers
Date: Thu, 16 Feb 2012 11:22:42 -0700
Organization: Cranial Interactive
Message-ID: <058F4CAC9BBC485EB01F869C8A09690B@NeilXPS9000>
MIME-Version: 1.0
Content-Type: text/plain;
	charset="us-ascii"
Content-Transfer-Encoding: 7bit
Thread-Index: AczsvZzEEMxbjqmVRO+RUyly7OYjhAAGZktg
Sender: "Neil Madsen" <lists@cranialinteractive.com>

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

-----Original Message-----
From: Jeffry Houser [mailto:jeffry@dot-com-it.com] 
Sent: February-16-12 8:13 AM
To: flex-dev@incubator.apache.org
Cc: Omar Gonzalez
Subject: Re: asdoc comments for flash player and SDK version numbers

On 2/16/2012 4:01 AM, Omar Gonzalez wrote:
> On Thu, Feb 16, 2012 at 12:38 AM, David Arno<david@davidarno.org>  wrote:
>
>> On Thu, 2012-02-16 at 18:05 +1100, Justin Mclean wrote:
>>> Hi,
>>>
>>> Was looking though some of the framework code and noticed that a lot 
>>> of
>> method are marked up with comments that are imported into documents 
>> re player version and the like.
>>>   Here's a typical section.
>>>       *  @langversion 3.0
>>>       *  @playerversion Flash 9
>>>       *  @playerversion AIR 1.1
>>>       *  @productversion Flex 3
>>>
>>> Going forward when adding new methods what are the values we should use?
>> Do we just go with current versions like so:
>>>       *  @langversion 3.0
>>>       *  @playerversion Flash 11.1
>>>       *  @playerversion AIR 3.1
>>>       *  @productversion Apache Flex 4.7
>>>
>> I'd really like it if we could figure out a way of getting rid of all 
>> that crap out of the framework as it makes reading the code far more 
>> difficult.
>>
>> David.
>>
> I'd love to find a solution that would let us continue to generate 
> ASDocs without polluting the code with tons of comments.

   I cannot adamantly disagree more with this statement.  I have never heard
anyone complain about too many comments before.  I have never experienced a
situation where I revisited code and thought "Gee, I wish I didn't write so
many comments."

  I think this can be important information to have; even the ASDoc /
Version information.  I do not believe that removing comments will help code
readibility in a significant way.  I do believe it may decrease code
understandability.

--
Jeffry Houser
Technical Entrepreneur
203-379-0773
--
http://www.flextras.com?c=104
UI Flex Components: Tested! Supported! Ready!
--
http://www.theflexshow.com
http://www.jeffryhouser.com
http://www.asktheflexpert.com
--
Part of the DotComIt Brain Trust