A general coding convention question/poll

[CDHBookingEdge]

When I was programming in C# and C++ I found myself using at least a variation of hungarian notation. By that I mean that member variables of a class had an "m_" in front of them and bools were written as bThisIsABool, etc. I notice that it seems like member variables in Flex/Flash have underscores in front of them and that's all. (I had a <bleep> of a time in one source I was looking at where the guy had the member var with two underscores and the local var with one underscore...drove my poor old eyes batty!)

So I was just wondering what types of coding conventions you all have found that help you in writing actionscript. Not just variable naming but also file organization and such and commenting and all that.

For example:
1) Do you feel that a file should have more than one class in it or not?

2) In C# and sharpdevelop, I fell in love with the #region it worked out really nicely in the IDEs that I used..you could organize things and just focus on one area closing out the others. And I also like how if you just typed /// it would put out a nice little area for you to document the function and such. What ways do you find that work for you as far as organizing your code?

3) What styles/strategies do you guys use for documenting classes and functions.


ya know those kinds of things.

Just thought it might make for good discussion and maybe I, and others can learn a thing or two. I'm sure that everyone has their own conventions and that's what works best for them. So it's all good, so long as you and the others in the organization follow them and so long as they provide good info to those who read the code and such.

Christopher

[Assertnfailure]

1) In AS 2, you simply can't have more than one class in a file. In AS 3 you can, however, only 1 class per file can be made public. There are times where i'd like to put multiple classes into a single file, but I can see the merit of a stricter policy to make it easier for other coders to find what they're looking for in your libraries.

2) javadoc/asdoc style is something more like this:
/**
* Description of the function.
*
* @param parameter 1 to pass to function
* @param parameter 2 to pass to function
* @return what is returned from the function
*/

Although typically only preferred for public methods/properties, so you can run your code through a tool to generate actual doc files of your comments.
Documentation for private members are usually at your own discretion, but in an ideal OOP environment, nobody else should have to look at your transparent code after you've committed it.

3) With Textmate, I used to have a specific grouping of properties/methods templated out for me when i created a new class. Something like...

//STATIC PROPERTIES
//STATIC METHODS

//PUBLIC PROPERTIES
//IMPLICIT GETTERS/SETTERS
//PRIVATE PROPERTIES

//INSTANTIATION METHODS

//EXPLICIT GETTERS
//PUBLIC METHODS

//PRIVATE METHODS
//EVENT HANDLERS

I dunno...I tend to play around and rearrange them from time to time, especially with the getters/setters. Although I've gotten a little more lazy lately using Eclipse.

[newblack]

Generally:

1. Depends on what you're making. If your application does more than exactly one thing, yes, I think that strict, granular OOP is the finest way to organize development efforts.

2/3. I use Eclipse + FDT (http://fdt.powerflasher.com/flashsite/flash.htm)- if you haven't used FDT for AS 2.0, it's so very much worth at least the 30 day trial. /** + return offers an auto-document region. MichaelxxOA turned me on to AS2Doc (http://as2doc.com/) for creating source documentation from javadoc-esque @tags.

As far as naming conventions, I kind of feel that it doesn't matter provided you stick to whichever convention you've chosen. Fully descriptive property/method names obviously makes code easier to revisit/share.

I find it particularly helpful when developers indicate when in an event chain a method is called. Documenting the execution order of a string of events and its purpose can prove more helpful than documenting that the method 'getUserLastName' gets the user's last name...

It's a good topic and one everyone interested in team development/open-source should think a lot about. Simon Wacker has created an ActionScript Coding Standards (http://www.simonwacker.com/blog/archives/000087.php) and while I think it's far too specific to be widely adoptable, he makes excellent cases for his assertions.

[newblack]

st33v beating me again...

[MichaelxxOA]

I have to agree with newblack, it doesn't matter much as far as convention as long as it is consistent throughout your code. And I also have to agree with st33v and javadoc. :-P

I use camelCase as in, getPersonsName();. For documentation I use javadoc and I usually only document my public methods/properties. The idea is that your code should be documentation enough.

As for file structure, I seperate all generic code into a classpath, any application specific code I put within a source directory for that application.

Also, take a look at AS2Doc it's pretty neat.

Michael

[jsebrech]

I've always found the javadoc syntax too ugly to adapt my comments to javadoc style comments. Where I work all developers have access to all code, so I tend to design comments so that you don't need any additional documentation. In practice this means explaining the purpose and public methods/properties of a class in a comment block at the top of the class.

Carefully grouping stuff into packages tends to become quite helpful as you produce more code. I have everything in a number of packages grouped into the same class path, so that all flash projects automatically have easy access to all library code.

[Assertnfailure]

:confused: I beat the relativist duo in a topic on conventions?? :confused: