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
_______________________________________________
use-revolution mailing list
[email protected]
Please visit this url to subscribe, unsubscribe and manage your subscription
preferences:
http://lists.runrev.com/mailman/listinfo/use-revolution
