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
