OpenXION Style Guide

English spoken here!
OpenXION is the English-like programming language based on Apple's HyperTalk.

No Installation!
Just download, unzip, & run!

In programming, a style guide is a set of recommendations designed to help make writing, reading, and maintaining your code easier. In much the same way that paragraph breaks, chapters, and punctuation can make a written document easier to read, small improvements in your code can improve readability and productivity. This is particularly important in multi-programmer projects where consistent programming practices makes everyone's life easier.

Style guides are not rules. They are simply suggestions that you can adapt or modify as you see fit. Three different programmers may use three different styles. In essence, studying style guides help you think about your programming in ways that will help you develop a better workflow.

Comments

Use of comments in your code is perhaps the single easiest way to increase readability. But it often seems like such a waste of time. When you've finished writing that great new function and it works, why bother to back and explain what appears to be painfully obvious?

Well, it may be obvious today but about a month or a year from now. Here is suggestion that makes commenting code almost painless.

Let's assume we need to write a new function to get user information. Consider the advantage of putting the comments in first to explain the program logic, then writing the code by filling in the blanks. function getUserData
    -- ask user for first and last name

    -- get user address

end getUserData Now we just fill in the blank lines with our program code and when complete our code is fully commented.

Break Up Large Files

Large files of program code can be arduous to navigate. Most often, it is best to break large files into several smaller ones. In particular, it is easy to put functions into separate files or into a single functions library file. Breaking functions out into separate files can greatly improve code reuse (see below).

Use Parenthesis & Spacing for Readability

Consider the following three lines of code: put 3 * 2 * 64 && getTotal
put ( 3 * 2 * 64 ) && getTotal
put (3*2*64) && getTotal All of them produce the same results, but to my eyes the second line is the most readable. The parentheses makes the order of execution more obvious, and the additional spaces improve reading. Food for thought?

Naming Conventions

As I recall, the concept of style guides in programming began with the need to develop naming conventions. Naming conventions imply the consistent use of function and variable names that make their use and scope (global, local, static) more obvious.

There are infinite possibilities for naming conventions, but they all involve two basic concepts:
    1. Consistent use of case in function names.
    2. Variable and Constant names that are easily recognizable and indicate scope.
Regarding case for function names, consider which you find more readable; getNewUser, getnewuser, get_new_user, or GetNewUser. The example getNewUser is called Camel Case and is a rather popular convention. Of course the idea here is not necessarily go with the flow, but find what works best for you and then standardize on it.

Naming variables is even more important. In the course of writing a single program, we may create dozens—even hundreds— of variables. A variables can be either global, shared, local, or static. These are variable scopes and define which parts of the program can use the specific variable. If you are unclear on variable scopes, see the definition for global in the documentation. A naming convention will help us know at glance the scope of any variable in our program.

As an example, assume we declare a local variable called myDate as follows: local myDate If we try to use myDate in another handler, it won't work because myDate is local to where it was declared. Of course, we won't be               immediately aware of this problem because the myDate name doesn't really tell us the scope.

However, if prefaced all of our variable names with a gl, sh, lo, and st (for global, shared, local and static), e.g. loMyDate or lo_myDate, we instantly know the scope of any variable anywhere it is used. And similar conventions can be used for declaring constants, parameters, properties, etc.

Code for Reuse

When programming, we need to be ever-vigilant for ways we might be able reuse the code we write. If you find a piece of that might be useful in other applications or throughout your existing app, it makes to put it in its own script or in a script file containing a library of functions for use whenever needed. Here's an example.

Assume we are writing an app and need to let the user choose a file to read from their hard disk. We can easily do that in 5-6 lines of code. But I can imagine this is something we will need quite often. Rather than rewriting that same 6 lines of code over and over, why not create a script file with a function that will do it whenever called? The possibilities for this type of reuse are endless and one of the secrets of productive programmers.

If you have several reusable functions, consider creating your own library. A library is simply a script file that contains a group of functions. You make all of the library files functions available to a script by using the include or require commands: include myLib.xn once without dialog
   or
require myLib.xn once without dialog See the documentation for differences between and the various options available for include and require. You may also want to explore the commands includeFile and includePath.

Conditions & Loops

Conditional statements, such as if...then...else...endif, and loops, such as repeat...end repeat, have numerous options and can be written in various styles. Without going into details about the possibilities, I will simply suggest that you explore all the documentation, example scripts, and other people's styles to determine which code styles make the most sense.

Size Does Not Matter

It's true! Coherency trumps brevity.
The Internet has done us a disservice with the endless comparisons of programming languages based on line of code or character count. The only two people that count in the software world are the end user and the programmer. And since the end user could care less what the code looks like, you are the only one that counts.

I feel the only good code is code I can easily read six months from now. Sure those brilliant one-liners are a interesting and creative exercise, but will you still love it tomorrow? Write code you want to read—we are well past the days when we had to eek every last bit of processor power and memory from the system.

Bottom Line

Refine, reduce, reuse.
Try to think seriously about your code and find ways to make it more readable and productive. It will cut your development, debugging, and program maintenance time, and the real bonus is that these techniques are applicable to any programming language you may use in the future.