Naming conventions [was: Food Fight]

[Dennis Brown]

Thank you all for your replies on your various style and naming  
conventions.  I have studied them all and have come up with a style I  
think will work for me.

I have started writing my personal style guide which I have appended  
below.  I have not included many of the good style suggestions of  
other's that I like yet, because I have been documenting the areas  
that are different from every one else's style.

I would appreciate anyone taking a look at what I am planning and  
comment if you see something else that I might want to take into  
consideration before I code it into stone ;-)

Dennis



My Personal Style Guide for Transcript Programming

Revolution Transcript has become my programming language of choice  
for my various projects.  These guidelines are designed to create a  
consistency of style in my scripts for my long term benefit in  
maintaining my code.  I will update this document as more issues  
become clear as needing formal structure.

I have chosen the postfix as opposed to the prefix tag scheme because  
I prefer to start my names as something pronounceable --with a silent  
tag.  It may not be applicable for all languages, but this style  
guide is specific to Transcript.  I also do not see the need for over  
specifying the variable types.


Naming Conventions for Variables, Constants, and Custom Properties

Appending the descriptive name with an identifier to determine its  
type and scope will aid in debugging and maintaining scripts.  It  
will also prevent a name used in a script from becoming a new keyword  
in a future release of the program.

Postfix  Meaning                        Examples             Comment

<num>G   Global variable or array       everyonesVar512G     Scope  
across stacks, use with caution*
W        Stack(window) global variable  myStackVarW          Scope  
across sub-stacks**
S        Script local variable          myScriptVarS         Scope  
across script
<num>    Local variable                 myVariable1          Scope  
inside handler
                                           x1,x2,y1,y2,z1,z2    use  
for x,y,z coordinates, or math
                                           i1,i2,i3,i4          use  
as loop indexes
                                           it,a1,b1,c1          use  
for intermediate math results

K        Constant                       myNumberK            Created  
with the constant command (RO)

P        Custom Property                myPropertyP           
Individual property of an object
P        Custom Property Set            myPropertySetP       Set of  
properties of an object (1d array)***


Notes:

Declare all globals at the top of the handler or top of the script if  
they are shared between handlers.
Declare locals at the top of the handler before executable statements.

Use variable names that are descriptive like "filePath1".  Names like  
"a1," "b1," which have no meaning should only be used for nameless  
intermediate results with a scope of less than a few lines --like the  
it variable would be used.

An ordinary variable can be converted into an array variable and back  
again with the split and combine commands, so a separate array  
designator is ambiguous.  Array variables are easy to spot because of  
their usual index: myArray1[index].

*Use globals sparingly. Code written with globals are sometimes  
difficult to debug since the globals can be changed anywhere. This  
means that if two stacks are loaded into the IDE at the same time,  
and both use a global called filePathG, and if either stack changes  
that variable, it is changed for both stacks.  This is great for  
adding new tools, but a nightmare for everything else.  Adding a  
unique number for each stack before the G will make globals with the  
same descriptive name unique between stacks.  There is also a  
registry of prefixes for global names that can be assigned individual  
developers or companies who write tools or otherwise might use  
globals for many users.  I think it would be just as unique placed  
anywhere (front, back, or middle) of the name.

**While this scope is not yet implemented, it should soon be out of  
necessity!  I will use this notation and declare all of these on a  
separate line so that a simple edit will change the scope after it is  
implemented:  global myStackVarW --fix

***My intention is to always use the array notation for accessing  
properties in sets.  I do not see any need to identify these  
differently than any other property because the context will show the  
difference.

Naming Conventions for Custom Handlers and Custom Functions

Capitalize the first character of a custom handler or function name  
to distinguish it from built-in commands and functions.  This will  
also help distinguish custom handlers and functions in the future if  
a new program release includes a new keyword or function that  
conflicts with yours.  I am considering if I should append something  
to the name to show where it is located --W,C,G for stack,card,group  
to make it easier to locate the scripts later.  Possibly F,B for  
front,back scripts also.

on mouseUp
    AddHandler 1,2
end mouseUp

on AddHandler param1,param2
    global resultW --fix
    put AddFunction(param1,param2) into resultW
end AddHandler

on AddFunction param1,param2
    return param1+param2
end AddFunction