Best Practices Question

[Richmond Mathewson]

Thanks for <http://revolution.byu.edu/design/bestpractices.html> and all 
the other connected pages there;
really good, sensible stuff, set out in a way that is much more 
comprehensible than most programming
manuals I have encountered.

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