Fourth World Scripting Style Guide
Adapted from The Michael and Richard Style Guide
This document may be distributed freely only in its complete, unmodified form, including this header and copyright information.
Whereas it is in the interest of all programmers to write code in a consistent, readable style, Richard Gaskin of Fourth World and Michael Silver of Barnacle Software have collaborated to produce a style guide for programming in SuperTalk, HyperTalk, and related scripting languages.
There are many reasons to use good style practice when writing code. Some of these reasons are:
It may take a little discipline at first, but a good style becomes natural very quickly and soon you will look at your old code and wonder who wrote it.
The authors, along with Ken Ray, Mark Hanrek, and others, have, in their courses of writing lots and lots of code, independently adopted or evolved most of the same conventions, and thus we concur that they must be pretty good. We have taken the few small differences between our styles and made what we feel is the better choice to give you, our guest, a well-thought-out, stable style that will serve you for years to come. You will be happy and all your dreams will come true.
You may have developed your own stylistic practices which you feel are better in some regards than what we present here. And they probably are. And while these are only guidelines, the more people stick to them, the more easily people will exchange code happily and live in peace. And in the end, isn't that all we really want?
Having said all that, it is never worthwhile to rewrite existing code simply to conform to these restrictions. Nor is it worthwhile to stick to a guidelines where the function or efficiency of the code is compromised. There is a fine line between maintaining more maintainable code and more efficient code. It is up to you to decide where that line is in your own code.
This document is a work in progress. We use it here in the course of teaching and working with contractors, and accordingly it is always being ammended and enhanced as experience dictates and time permits. If you have suggestions for tips and techniques which you would like to see included here, please email them to me.
Oh, and one last comment: the code in the examples may seem pointless. They are examples. That said, here is what you really came for.
1. Handler Descriptions
If a description of a handler or function is needed, it preceeds the handler with sufficient comment lines to link it visually with the handler definition.
-- -- doExample (give an example) -- -- This is an example of a handler definition. -- on doExample global gMyGlobal,gAnotherGlobal ... end doExample
2. Other Comments
Use comments liberally if you are not concerned about the script size. SuperCard, HyperCard, and Director currently have a 32K limitation for any single script, so scripts often run into this limit, and, unfortunately, comments may add considerably to the problem. Hopefully this limitation will be removed soon. Then comment liberally always.
If you must comment sparingly, be sure to comment places where the code is unusual: for example, workarounds. You may need to initialize a variable in two places or set the lockScreen to false (although it was never set to true) to workaround an engine problem. If so, you will probably not remember why that strange line of code is there the next time around until you delete it and break something.
NOTE: SuperCard users should remember that comments are removed when using Standalone Maker's encryption option. The same applies to Director users when compiling to Lingo's byte code.
on myHandler global gFilePath put cd fld "Names" into tNames get Directory(gFilePath,"MDOC") -- XFCN call put convertDirectory(it) into tDirectory if tNames = tDirectory then pass myHandler end myHandler
4. Variable Naming
In this section we advocate liberal use of what is commonly referred to as Hungarian notation, in honor of the famous Microsoft programmer Charles Simonyi, who is said to follow this practice obsessively. The value of Hungarian notation is that it provides a consistent method for determining the use and nature of a given container right in the name, without having to refer to the global declarations or parameter list. To varying degrees, this style has been adopted by many scripters in recent years, as is reflected in the product documentation for Allegiant products and others.
on myHandler pNumPeople,pNames global gFilePath global kMaxPeople,kMinPeople -- constants if pNumPeople > kMaxPeople then exit myHandler if pNumPeople < kMinPeople then exit myHandler repeat with i = 1 to the num of items in pNames put item i of pNames & cr after tFileData end repeat open file gFilePath write tFileData to file gFilePath close file gFilePath end myHandler
5. Other Considerations
if (the vis of wd "myWindow") then
if the vis of wd "myWindow" = true
MetaTalk, SuperTalk and some other languages also requires parantheses for some special cases such as substituting a variable name where it expects a literal. One-word literals do not have to be in quotes, except in some special cases. Which leads us to our next rule: