Best Practices Question

[Devin Asay]

Hi Bill,

On May 27, 2009, at 8:05 AM, Bill Andersen wrote:

> Can someone point me to a "Best Practices" or good itermediate  
> tutorial
> on programming in Rev.  I've been able to do quite a bit and can use
> the dictionary to learn how to use the language, but I'm having  
> trouble
> understanding how most people use Globals, Custom Properties, etc.
>
> I've read pro and cons on using globals.  I've tried to write  
> functions
> and pass params around to avoid them (which I think is best), but then
> there are times a global seems to be a better idea... OR would a  
> Custom
> Property be better?  I just don't know how others would do it.  I've
> looked through a lot of examples and it seems it is all over the  
> board!
>
> I know it isn't written in stone (and really a personal preference),
> but has someone put together a "Best Practices" document?

I teach a Revolution programming for non-programmers class, and a  
couple of years back I put together a fairly basic set of Best  
Practices. See <http://revolution.byu.edu/design/bestpractices.html>.  
Obviously there are many more issues than this, and as you said, much  
of it is determined by programmer preference. The Best Practices list  
I put together represents some of my own biases, to be sure, but are  
intended to help learners develop good habits and discipline as they  
write code.

As you mentioned there have been many wide ranging discussions here on  
the list debating the pros and cons of this or that issue, notably the  
recent discussion about custom properties. You're right that much of  
this boils down to what makes sense for you and seems logical for you.

If you're interested in some nitty-gritty discussion of best  
programming practices, based on the principles of interoperability of  
shared Revolution stacks and resources, you can do no better than look  
through the documents created by the Revolution Interoperability  
project at <http://tech.groups.yahoo.com/group/revInterop/>. Note that  
it's a Yahoo group that requires (I believe) you to register (I  
believe to see the materials. Under the leadership of many of the  
leading lights of the Rev developer community, notably Richard Gaskin  
and Ken Ray, the Interop project has done some serious thinking about  
best practices and come up with lots of good guidance.

Incidentally, Richard has summarized much of this work at <http://www.fourthworld.com/embassy/articles/scriptstyle.html 
 >.

Finally, a few random thought from people on this list. When I was  
putting together my simple beginners list I solicited feedback from  
folks on the list. For various reasons, including personal laziness, I  
haven't yet included them all. But you may find some of the remarks of  
interest.

## quote
Students should always write their programs as if someone else will  
later come along to either maintain or enhance it. It's a good habit  
to get into as it forces better design practices. When it comes to  
maintaining or more importantly adding code to a loop the last thing  
you want is problems figuring out where and how the loop control  
variable is modified.

See Richard Gaskin's Script Style Guide at http://www.fourthworld.com/embassy/articles/scriptstyle.html

Ken Ray:
I name all buttons exactly the same as their labels, without any  
spaces or punctuation, so for example a checkbox that says "Use  
meaningful names" would be named "UseMeaningfulNames" - this makes it  
unnecessary to look up the name of a button in order to address it in  
a script. The only times I break this habit is where conventional  
abbreviations are things that come to "top of mind" as an alternative  
(for example, a button that says "Download Now" would be named "DLNow"  
because "DL" is a very common alternative for "Download").

Similarly I name all fields based on the label that precedes it (if  
there is one) using the same approach. So a label field that says  
"First Name:" and has a text entry field next to it would have the  
entry field named "FirstName". I generally don't give names to label  
fields, but if I do need to, I follow the rule above and add "lbl" in  
front of it (so the label field I describe above would be called  
"lblFirstName" if I needed to address it).

Inspired by Kay Lan:
As much as possible, keep object names unique within a stack. It will  
make finding and changing references to object names in  scripts  
easier, should it become necessary.

Shari at gypsyware.com
Comment your scripts:  Agree again.  Sometimes naming the handler to  
match isn't enough, especially with a long script.  One thing I do  
with very long scripts with many if's and repeat loops nested, is to  
comment the beginning and ending of an IF or REPEAT, in order to match  
them up.  I've got scripts where it's nearly impossible to figure out  
which END goes with which beginning.  And if you're trying to  
troubleshoot, having things well labeled can be a lifesaver.

ME:
Hard-coding data in scripts and object inspectors is a Bad Idea™.  
Inevitably, runtime conditions will change over the life of your  
program, and the hard-coded data will no longer be valid, breaking  
your program. Instead, save data that could potentially change in text  
files or custom properties. In the case of dynamic information like  
file paths, it is best to dynamically derive them at runtime.

Addition to comments and/or if-then-else rule:
For very long or nested if or else clauses it is a good idea to  
comment sections of the structure so you know which 'end if' belongs  
with which 'if'.

Mark Wieder:
Keep standard handlers (i.e., mouseUp) as short as possible, putting  
the real code in separate handlers:

on mouseUp
   doSomething
end mouseUp

on doSomething
   --lots of code here
end doSomething
----------------------------------

Quote string literals:
Use "hello" instead of hello.

----------------------------------
And since you've already decided that not everybody will agree with  
all of
these:

Declare your local variables and enable the "variable checking by  
default"
option.
It will help prevent typos and cut down your debugging time.

## end quote

There! That's probably more than you bargained for. And I'm sure  
others will chime in with more advice. We all have plenty of that, for  
free. :-)
>
> We really need a Rev for Dummies book!

Well maybe it's not Rev for Dummies, but revolution.byu.edu is at  
least "Rev for Newbies". :-)

(BTW, there is a "Programming for Dummies" book that includes examples  
in Revolution as well as other languages. I haven't seen it so can't  
make any claims as to its quality.)

HTH,

Devin

Devin Asay
Humanities Technology and Research Support Center
Brigham Young University