You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@flex.apache.org by Justin Mclean <ju...@classsoftware.com> on 2012/02/16 08:05:09 UTC
asdoc comments for flash player and SDK version numbers
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
That's assume that anything submitted will be in the next release when it may not be. Perhaps just "@productversion Apache Flex" for now with no version number?
Do we try and match previous FP versions? ie if it runs in FP 10.2 use "@playerversion Flash 10.2".
Or do we don't bother adding this information at all and revisit at a later date? Anyone have a strong view on this?
Thanks,
Justin
Re: asdoc comments for flash player and SDK version numbers
Posted by Omar Gonzalez <om...@gmail.com>.
>
>
>
> Or do we don't bother adding this information at all and revisit at a
> later date? Anyone have a strong view on this?
>
> Thanks,
> Justin
>
>
I do think we should figure out what the proper values are to reduce the
amount of work we have to do when its time to package a release by not
having to go through the entire SDK to make sure all the documentation is
ready.
Maybe this becomes part of patch acceptance? Perhaps as part of accepting
a patch we require that the code has the required documentation and
automated tests to verify and we provide guidelines for authoring them? I'm
going to try to dig through some other Apache projects and see if they
define this somehow on their project sites, or perhaps a mentor can provide
some guidance here?
-omar
Re: asdoc comments for flash player and SDK version numbers
Posted by Haykel BEN JEMIA <ha...@gmail.com>.
It is actually detailed, just look at the source code of UIComponent as an
exmaple, the class documentation alone is 134 lines long!! When I read the
source code I generally only look at the first lines of the documentation
to have general idea. If I need more details I read the
generated HTML documentation which is much easier to read.
Haykel
On 16 February 2012 15:56, almansour belleh blanco <zabouzamomochi@gmail.com
> wrote:
> Well, it is not really detailed documentation. It's a documentation
> generated
> automatically and for that you have just to follow a common procedure
> for writing
> the comments. It is useful so that when your code is read by other
> developers, it can
> be better understood.
>
>
>
> 2012/2/16 Haykel BEN JEMIA <ha...@gmail.com>:
> > Personally I never write detailed documentation while developing. I
> > generally write a short description and the detailed documentation is
> > either written by someone else or in another documentation pass, which
> can
> > be done in other files.
> >
> > I have suggested stub classes in an earlier e-mail because I think this
> > could be useful also for IDEs. They would not require the whole source
> code
> > for auto-completion, documentation etc.
> >
> > Haykel
> >
> >
> >
> >
> > On 16 February 2012 14:41, Carol Frampton <cf...@adobe.com> wrote:
> >
> >> I am totally against stripping out the asdoc. Who do you think writes
> the
> >> asdoc? We do. It is just as important as the code. If you strip it
> out
> >> it won't be kept current. It should be part of any code review.
> >>
> >> Carol
> >>
> >> On 2/16/12 4 :15AM, "Omar Gonzalez" <om...@gmail.com> wrote:
> >>
> >> >>
> >> >> Perhaps a script to strip out all comments and a way to create
> patches
> >> >> ignoring missing comments would be useful?
> >> >>
> >> >> Thanks,
> >> >> Justin
> >> >
> >> >
> >> >I'm not quire sure what you mean. The ideal solution would be to figure
> >> >out
> >> >a way to keep comments in such a way that the during development
> they're
> >> >not in our files but at release or at patch submission the proper
> >> >documentation is there.
> >> >
> >> >--
> >> >Omar Gonzalez
> >> >s9tpepper@apache.org
> >>
> >>
>
>
>
> --
> Mansour Blanco
> Software engineer
> Stackoverflow: http://stackoverflow.com/users/612920/mansuro
> Blog: zuro.blogspot.com
> github: https://github.com/Mansuro
>
Re: asdoc comments for flash player and SDK version numbers
Posted by almansour belleh blanco <za...@gmail.com>.
Well, it is not really detailed documentation. It's a documentation generated
automatically and for that you have just to follow a common procedure
for writing
the comments. It is useful so that when your code is read by other
developers, it can
be better understood.
2012/2/16 Haykel BEN JEMIA <ha...@gmail.com>:
> Personally I never write detailed documentation while developing. I
> generally write a short description and the detailed documentation is
> either written by someone else or in another documentation pass, which can
> be done in other files.
>
> I have suggested stub classes in an earlier e-mail because I think this
> could be useful also for IDEs. They would not require the whole source code
> for auto-completion, documentation etc.
>
> Haykel
>
>
>
>
> On 16 February 2012 14:41, Carol Frampton <cf...@adobe.com> wrote:
>
>> I am totally against stripping out the asdoc. Who do you think writes the
>> asdoc? We do. It is just as important as the code. If you strip it out
>> it won't be kept current. It should be part of any code review.
>>
>> Carol
>>
>> On 2/16/12 4 :15AM, "Omar Gonzalez" <om...@gmail.com> wrote:
>>
>> >>
>> >> Perhaps a script to strip out all comments and a way to create patches
>> >> ignoring missing comments would be useful?
>> >>
>> >> Thanks,
>> >> Justin
>> >
>> >
>> >I'm not quire sure what you mean. The ideal solution would be to figure
>> >out
>> >a way to keep comments in such a way that the during development they're
>> >not in our files but at release or at patch submission the proper
>> >documentation is there.
>> >
>> >--
>> >Omar Gonzalez
>> >s9tpepper@apache.org
>>
>>
--
Mansour Blanco
Software engineer
Stackoverflow: http://stackoverflow.com/users/612920/mansuro
Blog: zuro.blogspot.com
github: https://github.com/Mansuro
Re: asdoc comments for flash player and SDK version numbers
Posted by Haykel BEN JEMIA <ha...@gmail.com>.
Personally I never write detailed documentation while developing. I
generally write a short description and the detailed documentation is
either written by someone else or in another documentation pass, which can
be done in other files.
I have suggested stub classes in an earlier e-mail because I think this
could be useful also for IDEs. They would not require the whole source code
for auto-completion, documentation etc.
Haykel
On 16 February 2012 14:41, Carol Frampton <cf...@adobe.com> wrote:
> I am totally against stripping out the asdoc. Who do you think writes the
> asdoc? We do. It is just as important as the code. If you strip it out
> it won't be kept current. It should be part of any code review.
>
> Carol
>
> On 2/16/12 4 :15AM, "Omar Gonzalez" <om...@gmail.com> wrote:
>
> >>
> >> Perhaps a script to strip out all comments and a way to create patches
> >> ignoring missing comments would be useful?
> >>
> >> Thanks,
> >> Justin
> >
> >
> >I'm not quire sure what you mean. The ideal solution would be to figure
> >out
> >a way to keep comments in such a way that the during development they're
> >not in our files but at release or at patch submission the proper
> >documentation is there.
> >
> >--
> >Omar Gonzalez
> >s9tpepper@apache.org
>
>
Re: asdoc comments for flash player and SDK version numbers
Posted by Justin Mclean <ju...@classsoftware.com>.
Hi,
> I'm not quire sure what you mean. The ideal solution would be to figure out
> a way to keep comments in such a way that the during development they're
> not in our files but at release or at patch submission the proper
> documentation is there.
Yep exactly what I was suggesting. Use a script to strip out unwanted comments once code is checked out. Work on those files but when submitting patches missing comments are ignored or added back in when committing to SVN. Don't know exactly how you would do that - probably not easily possible. Moving the comment out to separate files is probably simpler (and modifying the documentation generation process) but as someone else said that would make it harder to keep code and docs in sync.
Justin
Re: asdoc comments for flash player and SDK version numbers
Posted by Martin Heidegger <mh...@leichtgewicht.at>.
This is true the same time as its problematic. If we keep the
documentation in english up-to-date as
we code and the other languages get outdated then its a essential
quality issue. Also having a completely
different workflow for english than the other languages pushes a little
to ignoring the other languages.
(The documentation is available in english anyways).
yours
Martin.
On 16/02/2012 22:41, Carol Frampton wrote:
> I am totally against stripping out the asdoc. Who do you think writes the
> asdoc? We do. It is just as important as the code. If you strip it out
> it won't be kept current. It should be part of any code review.
>
> Carol
>
> On 2/16/12 4 :15AM, "Omar Gonzalez"<om...@gmail.com> wrote:
>
>>> Perhaps a script to strip out all comments and a way to create patches
>>> ignoring missing comments would be useful?
>>>
>>> Thanks,
>>> Justin
>>
>> I'm not quire sure what you mean. The ideal solution would be to figure
>> out
>> a way to keep comments in such a way that the during development they're
>> not in our files but at release or at patch submission the proper
>> documentation is there.
>>
>> --
>> Omar Gonzalez
>> s9tpepper@apache.org
>
>
Apache copyright notice question (probably for a mentor)
Posted by Carol Frampton <cf...@adobe.com>.
How do I change the copyright that asc prints out for Apache?
Now:
./asc currently prints out
ActionScript 3.0 for AVM+
version 1.0 build cyclone
Copyright (c) 2003-2007 Adobe Systems Incorporated
Copyright (c) 1998-2003 Mountain View Compiler Company
All rights reserved
Usage: .....
Does the entire Apache license template, below, have to print out?
Copyright [yyyy] [name of copyright owner]
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Carol
Re: asdoc comments for flash player and SDK version numbers
Posted by Carol Frampton <cf...@adobe.com>.
I am totally against stripping out the asdoc. Who do you think writes the
asdoc? We do. It is just as important as the code. If you strip it out
it won't be kept current. It should be part of any code review.
Carol
On 2/16/12 4 :15AM, "Omar Gonzalez" <om...@gmail.com> wrote:
>>
>> Perhaps a script to strip out all comments and a way to create patches
>> ignoring missing comments would be useful?
>>
>> Thanks,
>> Justin
>
>
>I'm not quire sure what you mean. The ideal solution would be to figure
>out
>a way to keep comments in such a way that the during development they're
>not in our files but at release or at patch submission the proper
>documentation is there.
>
>--
>Omar Gonzalez
>s9tpepper@apache.org
Re: asdoc comments for flash player and SDK version numbers
Posted by Omar Gonzalez <om...@gmail.com>.
>
> Perhaps a script to strip out all comments and a way to create patches
> ignoring missing comments would be useful?
>
> Thanks,
> Justin
I'm not quire sure what you mean. The ideal solution would be to figure out
a way to keep comments in such a way that the during development they're
not in our files but at release or at patch submission the proper
documentation is there.
--
Omar Gonzalez
s9tpepper@apache.org
Re: asdoc comments for flash player and SDK version numbers
Posted by Justin Mclean <ju...@classsoftware.com>.
Hi,
> 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.
I do find it slightly annoying but I do like that it tells you what version of the SDK etc the method requires. That's useful. It's also passed though to the generated documentation which is again useful. The excessive blank lines (caused by bracket style) and unnecessary multiline comments annoy me more but we have to work with what we've got :-)
Perhaps a script to strip out all comments and a way to create patches ignoring missing comments would be useful?
Thanks,
Justin
Re: asdoc comments for flash player and SDK version numbers
Posted by Martin Heidegger <mh...@leichtgewicht.at>.
On 16/02/2012 18:40, Justin Mclean wrote:
> Hi,
>
> The xml looks like a distinct possibility even if it is harder to maintain. I's also assume that the XML skeleton was generated via some tool/script. It may break tool tip help in Flash Builder if we went down this path.
>
> Justin
"Big-swcs" have the documentation as a special part of the swc. Not in
the common document format. It would needed to be compiled from the xml
docs.
yours
Martin.
Re: asdoc comments for flash player and SDK version numbers
Posted by Justin Mclean <ju...@classsoftware.com>.
Hi,
The xml looks like a distinct possibility even if it is harder to maintain. I's also assume that the XML skeleton was generated via some tool/script. It may break tool tip help in Flash Builder if we went down this path.
Justin
Re: asdoc comments for flash player and SDK version numbers
Posted by Omar Gonzalez <om...@gmail.com>.
On Thu, Feb 16, 2012 at 1:24 AM, Martin Heidegger <mh...@leichtgewicht.at>wrote:
> On 16/02/2012 18:21, Omar Gonzalez wrote:
>
>>
>> how do they link the appropriate XML documents to the correct class and
>> methods?
>>
>> -omar
>>
> I can see that they use the signature of the methods to map the
> translation to the content [1].
>
> yours
> Martin.
>
> [1]https://svn.apache.org/**repos/asf/incubator/flex/**
> whiteboard/frameworks/**projects/framework/bundles/de_**
> DE/docs/mx.core.xml<https://svn.apache.org/repos/asf/incubator/flex/whiteboard/frameworks/projects/framework/bundles/de_DE/docs/mx.core.xml>
>
>
I wonder if a tool exists for generating these files? This looks like a
complete nightmare to try to generate or maintain manually.
-omar
Re: asdoc comments for flash player and SDK version numbers
Posted by Martin Heidegger <mh...@leichtgewicht.at>.
On 16/02/2012 18:21, Omar Gonzalez wrote:
>
> how do they link the appropriate XML documents to the correct class and
> methods?
>
> -omar
I can see that they use the signature of the methods to map the translation to the content [1].
yours
Martin.
[1]https://svn.apache.org/repos/asf/incubator/flex/whiteboard/frameworks/projects/framework/bundles/de_DE/docs/mx.core.xml
Re: asdoc comments for flash player and SDK version numbers
Posted by Omar Gonzalez <om...@gmail.com>.
On Thu, Feb 16, 2012 at 1:16 AM, Martin Heidegger <mh...@leichtgewicht.at>wrote:
> The documentation for languages except english are generated using xml
> files.
> I never tried it but I guess you can use similar files for english as well
> and remove all
> the english documentation out of the sources.
>
> yours
> Martin.
>
>
> You're talking about ASDoc comment blocks? If they're externalized to XML
how do they link the appropriate XML documents to the correct class and
methods?
-omar
Re: asdoc comments for flash player and SDK version numbers
Posted by Martin Heidegger <mh...@leichtgewicht.at>.
The documentation for languages except english are generated using xml
files.
I never tried it but I guess you can use similar files for english as
well and remove all
the english documentation out of the sources.
yours
Martin.
On 16/02/2012 18:01, 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. Like you said it'd make
> the code a lot easier to read through, but I have never heard of any
> solutions for this. I remember either reading or hearing someone speak
> about an attempt at doing this, but I don't know where that ended up. Right
> now the only thing I can think of is reducing each block to an include()
> which would suck as well but would at least reduce some of these comments
> from 50+ lines to 1. However it'll be a lot of includes in a single class
> file. Any other ideas?
>
> -omar
>
RE: asdoc comments for flash player and SDK version numbers
Posted by Gordon Smith <go...@adobe.com>.
> The comment adds nothing.
Well, at least it makes something show up in ASDoc for the 'title' property. Would you want nothing at all to appear?
I see two problems:
1. You don't document a setter as setting anything because the getter/setter pair appears in ASDoc as a single property that you can get or set.
2. A property like 'title' should be described in non-self-referential terms, such as "The String displayed at the top of the Panel".
- Gordon
-----Original Message-----
From: Neil Madsen [mailto:lists@cranialinteractive.com]
Sent: Thursday, February 16, 2012 11:39 AM
To: flex-dev@incubator.apache.org
Subject: RE: asdoc comments for flash player and SDK version numbers
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:cframpto@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" <om...@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
RE: asdoc comments for flash player and SDK version numbers
Posted by Neil Madsen <li...@cranialinteractive.com>.
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:cframpto@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" <om...@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
Re: asdoc comments for flash player and SDK version numbers
Posted by Jeffry Houser <je...@dot-com-it.com>.
On 2/16/2012 1:40 PM, Omar Gonzalez wrote:
> 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.
Fair enough; if the comment communicates no value; I have no issues
deleting it.
> All this kind of crap just makes it more difficult to read through code and
> provides little to no deeper of an understanding.
I completely disagree; but to each their own. Comments, even long
ASDocs have never
> 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 would, personally, prefer the former version, as the comment more
clearly explains what the variable is than the longer variable name. I
wouldn't complain about a combination of the two; using both the longer
variable name and the comment. But, I do disagree that the latter is
better.
>
> I just turned 6 lines in the source code to 1 and it still expresses
> exactly what its intention is.
I disagree.
--
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
Re: asdoc comments for flash player and SDK version numbers
Posted by Carol Frampton <cf...@adobe.com>.
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" <om...@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
Re: asdoc comments for flash player and SDK version numbers
Posted by Omar Gonzalez <om...@gmail.com>.
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
RE: asdoc comments for flash player and SDK version numbers
Posted by Neil Madsen <li...@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<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
Re: asdoc comments for flash player and SDK version numbers
Posted by Jeffry Houser <je...@dot-com-it.com>.
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
Re: asdoc comments for flash player and SDK version numbers
Posted by Haykel BEN JEMIA <ha...@gmail.com>.
What about creating stub classes for the documentation? I think this how it
is done for PHP. This could make maintenance of documentation harder though.
Haykel
On 16 February 2012 10:01, Omar Gonzalez <om...@gmail.com> 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. Like you said it'd make
> the code a lot easier to read through, but I have never heard of any
> solutions for this. I remember either reading or hearing someone speak
> about an attempt at doing this, but I don't know where that ended up. Right
> now the only thing I can think of is reducing each block to an include()
> which would suck as well but would at least reduce some of these comments
> from 50+ lines to 1. However it'll be a lot of includes in a single class
> file. Any other ideas?
>
> -omar
>
Re: asdoc comments for flash player and SDK version numbers
Posted by Omar Gonzalez <om...@gmail.com>.
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. Like you said it'd make
the code a lot easier to read through, but I have never heard of any
solutions for this. I remember either reading or hearing someone speak
about an attempt at doing this, but I don't know where that ended up. Right
now the only thing I can think of is reducing each block to an include()
which would suck as well but would at least reduce some of these comments
from 50+ lines to 1. However it'll be a lot of includes in a single class
file. Any other ideas?
-omar
Re: asdoc comments for flash player and SDK version numbers
Posted by David Arno <da...@davidarno.org>.
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.