[RESOLVED] Best practices for describing/commenting Custom Classes

[badaboom55]

Hello All,

Newish to OOP and Class programing in AS3.0, also new to the production team environment where other (wiser, more experienced) developers will be using and looking at my code and Classes on a regular basis.

So, I'm trying to develop a semi-standardized Class template to make it easier on the other team members to parse through my code. If you look at a lot of the classes that are freely available for download around the web, a lot of times you'll see a good sized chunk of comments at the top of the .AS file.
Usually these consist of copyrights and usage rights, e.g. "This class was made by jo' mamma for use in x, y, z 2020" and maybe a plain english description of what the Class is attempting to do.

Anyway, I've never put any of that info in my Class files before, because well, I've always been the only one looking at my code.

So, I wanted to get some other developer's opinions on what kind of information and syntax would be the MOST helpful to see in the comments at the top if they were opening a .AS file that they've never seen before?

Are there any "best practices" or "semi-standard templates" documented out there on the web? Even if it's not AS3.0 specific... I mean a Class is a Class regardless of language... so even if the syntax is different, I imagine the general info useful to a C+ developer would also be useful to an AS3.0 developer?

Aside from the general guidlines, I have seen this at the top of some .AS files:

// @(#) MyCustomClass.as

What does the "@(#)" mean, exactly?

[guardiankitty]

(let me know if I am completely going the wrong way with this)

For me, I really love JavaDoc.

What this is, is a way to comment your code in a way that IDE's and Documentation Generators can parse.... best part is it is really easy and effective to use.


How to use:

Lets say you have a function/class/method/variable/et al...

like the following:

function a(b:Number, c:String):MovieClip{
var d:MovieClip=new MovieClip();
d[c]=b;
return d;
} 

Who knows what the heck this code is used for... and how and when it can be used in a project! If you forget (oh and If you knew me, you would know I already forgot ...) what its uses are for, then you are do much more harm then good when trying to edit it.

But, if you comment using JavaDoc, as follows:

/** Guardiankittys IceCream Maker Function: 
This function is used in the Ice Cream class, and what it does is creates a new movieclip instance,
takes a given string and number to give a new property to the movieclip...
 *@param b This is the amount of IceCream Cones are left!
 *@param c This is the flavor... (chocolate, blue, or vanilla)
 *@author GK>'.'<
 *
 */

function a(b:Number, c:String):MovieClip{
var d:MovieClip=new MovieClip();
d[c]=b;
return d;
} 

So whats the benefit? Well one instance is if you use flash develop (as I have grown to not be able to live without), when you start to type out this function,... it will pop up with your description message (kind of like flash's code completion help,... but better).

Then for each 'param' (aka parameter) it will show the 'code hints/descriptions' that you have written!

This can be used for functions/methods and classes. (so when you type out a new class, it will also give you a rundown on what that class does)

This really really really comes in handy dealing with old code (and I have such a bad memory... I always forget why I wrote something in a specific way... then write it a different way just to find the same unbreakable wall that leads me back to doing it the way it originally had it... (at these times, I feel like the dumbest and smartest person in the world... its a great feeling)), . Also it is perfect when dealing with someone elses API or code.



The second great use is that of Document Generation. by running some programs you can generate html help/reference/api documents.





again, its as simple as writing a normal block comment, but with an extra star... /**


First line is description, then every other line you can type a keyword that begins with the @ symbol (param, author, and about 9 or so in total)


For more info, http://en.wikipedia.org/wiki/Javadoc



Hope this helps ya out,

as far as //@(#) ClassName.as goes... Looks like a shebang of some sort, not really sure what uses it or why... Maybe its just to get your bearings when working on a .as file... to make sure you know your in the right place when your editing a class... but not really sure.



See the attached... its an example of using JavaDoc to autocomplete/hints





-GK >'.'<

[5TonsOfFlax]

asdoc (the actionscript equivalent of javadoc) is included in the free flex sdk. It's relatively easy to set flashdevelop up to call asdoc for you and generate nice friendly html documentation of your entire project.

[badaboom55]

Thanks for the input!

So, I see '@' has a specific meaning when used in Javadoc, i.e. as a tag... so I'm guessing there's not really a "universal-ish" way to use '@', because I'm sure it would change based on personal preference, language, etc? I guess it's use is better determined by the context of whatever follows it =)

As for ASDoc, I'll have to explore that further...

I started as an Animator/Designer using Flash and have gradually moved into AS3.0 development... but I've never really explored the 15 dozen tools I COULD use to write/edit .AS files. I've always just stuck with the Flash GUI because most of my projects still use a ton of artwork and graphic assets, so I like being able to bounce around in my library, the stage, and the .AS files... but perhaps migrating to a more robust development environment is the thing to do.

Plus, Adobe's software suite is so muddled with feature-sets that are duplicated in several of their applications, that you can do just about anything in just about any Adobe software... hell, I think after I installed CS4, .as files by default opened in Dreamweaver. Even odder, .XML files wanted to open in Illustrator.

ANYWAY, as for ASDoc, I'll do some further reading... but how would I best use that with developing AS files? Could I stay within Flash, or should I migrate to some other edit program?
Is the chief purpose of ASDoc to generate HTML reference (like the ActionScript 3.0 Language Reference)?

Anyway, I'm not sure I'll need to jump into generate complete reference documents quite yet... I was more after a preferred way to document classes and such... and what do you know, in Adobe's ASDoc documentation, I found a conveniently titled section: "Documenting ActionScript elements"
http://livedocs.adobe.com/flex/3/htm..._4.html#189665

In fact, it seems very similar to Javadoc, so thanks for pointing me in the right direction!!

[guardiankitty]

I've always just stuck with the Flash GUI because most of my projects still use a ton of artwork and graphic assets, so I like being able to bounce around in my library, the stage, and the .AS files... but perhaps migrating to a more robust development environment is the thing to do.

Please dont feel that I am FlashDevelops pimp-...but

I like to have both open (both= [flash, flashdevelop]) at the same time... when typing code in flashdevelop you can hit the classic 'ctrl ENTER', and it works just the same (flash IDE compiles the code, and displays it in the development player)

Since I code a great deal in flash, I have two monitors set up on my computer... this works great for displaying them both at the same time.

ANYWAY, as for ASDoc, I'll do some further reading... but how would I best use that with developing AS files? Could I stay within Flash, or should I migrate to some other edit program?

Well here is the issue, javaDoc can be used to describe a program, but it is also a type of comment.

javaDoc (the program) is the name of a parser, that takes your java classes and creates a html API reference/documentation.

javaDoc (the type of comment) are the block comments which start with /** (in as2/3). All these are, are a way to parse regular comments from the ones that should be noted and parsed.
(I curse a great deal too much in my comments myself... so I make sure not to javaDoc those...)

It does not matter what you use the parsed comments for,... it truthfully can be used for anything. Originally used for generating documentation, but also can be used for code hints and auto completion, and I am sure someday someone will come out with another cool thing you can do with them, that makes programming that much more less insane.

ASDoc === javaDoc (the program) for actionscript;

You can use javaDoc (the type of comment) in the flash IDE, regardless of the fact that it wont do anything for you. It is always better to document your code then to not. Also if anyone else ever uses your code, they will be happy that you did.

Is the chief purpose of ASDoc to generate HTML reference (like the ActionScript 3.0 Language Reference)?

Yep

I was more after a preferred way to document classes and such... so thanks for pointing me in the right direction!!

Hope this helps, and good luck!!!

-GK>'.'<

[badaboom55]

Thanks, after reading through the documentation on ASDoc (the program/tool), it outlines the tags and guidelines to formatting ASDoc comments (the comment). ASDoc comments use different tags than JavaDoc comments, but similar formatting.

(I curse a great deal too much in my comments myself... so I make sure not to javaDoc those...)

Ditto... one day my project lead double-clicked a .SWF I had published, and instead of opening in Firefox as normally is the case, it launched in Flash and his Output Panel starting cursing like a sailor with scurvy.