[RESOLVED] Best practices for describing/commenting Custom Classes

[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 >'.'<