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:jef...@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<da...@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
