At some point in everyone's career, we all write crappy code (except my friend Mark Lucas, but he's in a class by himself). You know the kind: You go back to it six months later to add new features or better error-checking, and you have no idea what you were doing. It's "spaghetti code", and it can eat a lot of time as you try to figure things out all over again. That's where this document comes in.
A few healthy habits can make your code more robust and your workday shorter. While they may require a little self-discipline at first, if you find these practices useful and adopt them in your daily work they'll become second-nature and eventually require no extra effort at all.
There are many reasons to use good style practice when writing code, including:
The tips presented here reflect some of the best practices of many world-class scripters, and we should take a moment to acknowledge them here:
Michael Silver, Ken Ray, Mark Lucas, and Mark Hanrek are some of the best SuperCard scripters I've known, and it was while we were sharing code that we discovered that we had each independently developed pretty much the same code style. The first draft of this document reflected our common interest in SuperTalk, and was accordingly more limited in scope. It was distributed as part of a panel discussion on scripting techniques at the SuperCard Developer Conference in 1996, the year SuperCard 2.5 won the Mac Eddy award for Best New Multimedia Authoring Tool.
Since then this document has been revised many times, expanding its scope to include new tips for other similar scripting languages. Along the way I've collected valuable tips from a great many programmers, including Scott Raney, Kevin Miller, Steven McConnell, Jad Santos, and Alex Bronstein. With the things these folks have taught me, this document should hopefully be useful for scripters who prefer just about any HyperTalk dialect, and a few others besides.
As you read these tips, you may feel at times that where you code style differs you kinda like it that way. That's okay. If it works for you, it don't need fixin'.
These are only guidelines, and the more people use them the more easily people will exchange code happily, solve problems more quickly, spend more time with their families, and create an ever better world.
Having said all that, it is never worthwhile to rewrite existing code simply to conform to these suggestions. Nor is it worthwhile to stick to a guideline where the function or efficiency of the code is compromised. There is a fine line between making 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 suggests and time permits. If you have ideas for tips and techniques which you would like to see included here, please email them to me at email@example.com.
With all that out of the way, here's the beef:
General Scripting Techniques
A few techniques for getting the spaghetti out of your code....
Clarify Program Flow
One way to fight spaghetti code is to make sure your code's logic is self-evident. For example, if you have one long handler which takes care of a variety of startup stuff, you could break that down into multiple handlers which handle only specific related tasks. If you use descriptive names, you'll have no trouble grasping how the first handler works:
The extra time required by the interpreter to handle these separate calls is trivial, and isolating specific sets of related routines in this way can help you track down the source of errors during debugging.
One good technique for making sure your code's flow is evident is to write the comments first. Just make an outline of what the code needs to do in comments, then go back and fill in between them with the actual execu
--=============================================-- -- WINDOW ROUTINES -- -- -- DocWindowRect() -- -- Returns the default size for new document windows -- function DocWindowRect put the screenrect into r add 4 to item 1 of r add 4 to item 2 of r subtract 4 from item 3 of r subtract 4 from item 4 of r return r end DocWindowRect -- -- UpdateAllWindows -- -- Allows each open window to refresh itself -- on UpdateAllWindows