incubator-flex-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gordon Smith <gosm...@adobe.com>
Subject RE: asdoc comments for flash player and SDK version numbers
Date Thu, 16 Feb 2012 20:20:59 GMT
> 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" <omarg.developer@gmail.com> wrote:

>On Thu, Feb 16, 2012 at 10:22 AM, Neil Madsen
><lists@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



Mime
View raw message