Coding Convention Discussion

Discussion about Coding Conventions for this wiki.

It would be good to have a standard pattern for handlers. For example, on the ancestor page there is a blank line after the handler name, while on the frameTempo page, there is not. I believe that Robert Tweed has already worked out a standardised method for naming handlers and variables for his OpenLingo? initiative. It might be a good idea to adopt that. Robert? -- James Newton

I agree that we should call the CodingConvention Robert posted standard. We don't have to be overly strict about this tho - it should be more as a recommendation, than a rule IMO. -- Thomas Schmall

For reference, here's the summary of the openLingo convention that I posted on Direct-L a while ago:

Prefixes

• p - Public Property
• _ - Private property or handler
• a - Argument (a.k.a. parameter, but "a for argument" avoids confusion with "p for property")
• v - local Variable
• g - global variable (discouraged though)

__ - Private global: similar in purpose to a static variable, access through wrapper functions only

[NB: these characters were also chosen to be visually distinctive, which is why characters like "i" and "l" are not used at all]

Suffixes

• List - The variable is a list (a recommendation, not a requirement)
• Handler names: name in the form of a verb, describing the action performed by the handler, e.g., vObj.flipHorizontal()
• Instance names: names in the form of a noun describing the object, e.g., vApple, vPear

(Short variables: i, j, x, y, etc., are not generally recommended, but are OK for very short chunks of code where their use is not confusing, i.e., short loops, etc.

No prefix is used for handlers as it is mostly redundant. The only time a handler name might conflict with a property name is where the handler name begins with "p". For some reason the only example I can think of is pass() and pAss ;-) Care must therefore be taken to avoid such conflicts, but since they are unlikely anyway, not much care is needed. -- Robert Tweed

When I was working on the behaviors for Director 8.0, the official Macromedia line was to use no prefix for properties set using the getPropertyDescriptionList() handler. The reasoning behind this was that the property names appear in the scriptList for the sprite. Just as sprites have a .color property with no prefix, so a behavior should have (say) a .defaultBrushColor with no prefix, to indicate that this is an core property of the behavior.

I notice that the properties added in D8.5 do not follow this rule, so perhaps it was changed, perhaps forgotten.

Personally, I have extrapolated the original official line, and I use no prefix for the public properties of an object, and a p- prefix for all private properties. In a similar spirit, I use no prefix for public handlers, but I use an m- prefix for private handlers. To distinguish public custom handlers from built-in event handlers (such as mouseUp), I use an uppercase intitial letter. This gives me:

 on PublicHandler()
 on mPrivateHandler()

Another official Macromedia recommendation is to use parentheses after the handler name:

 on new(me)
 on MovieScriptHandler()
 on GlobalHandler(aParameter)

The D8.5 behaviors also introduced a description section before each handler:

 -----------------------------------
 --PURPOSE: General clean up.
 --ACCEPTS: 'me' as an instance of this script.
 --AFFECTS: Used if an input list or instance property is modified
 --RETURNS: Nothing.
 -----------------------------------
 on endSprite(me)
   -- do stuff
 end endSprite

Handlers end with 'end handlerName', even though neither the handler name nor even 'end' is required. -- James Newton