Programming Style
Bill Kramer – April 2007
Everyone has there own style in lots of things. Whether it is the type of clothing you like to wear, type of vehicle you travel in, or where you live; your style helps define you. Another place you can apply some style is in programming LISP functions. Over the past few years I’ve seen quite a few styles as the author of Hot Tip Harry. Some of them I like while others I find difficult to read simply because they are too different.
Before I go too far on a tirade about style in programming I should mention an old saying in the world of programming regarding the defining of “my” versus “your” programs. This is from “way back”, when I used to work with teams of programmers in arcane languages such as FORTRAN and COBOL. It goes something like this: “My” program is an algorithmic gem with subtle comments and meaningful variable names while “your” program is a spaghetti plate full of nonsense. With that in mind let me introduce some concepts of programming style in AutoLISP that I’ve adopted over the years. If you encounter some code I wrote that does not conform to this style suffice it to say that just because it is a style does not make it a standard.
The first bit of styling I like to follow is to use the FORMAT code option in the Visual LISP editor. The default settings are just fine. Running the format code command over your program will indent new nesting levels in the code automatically and make missing parenthesis or sections of code immediately obvious. How do you end up with missing sections of code? Easy when you are coding conditionals and want to simply test code with known working input before implementing the error catches and reasons behind the conditional code structure in the first place. Before Visual LISP came along those of us who used indented source code relied on programs called “pretty printers” that took a list and created an automatic indent that was “easy to follow”. Pretty printer functions are some of the earliest programming tools ever created by programmers for programmers following the creation of the high level language concept.
Another favorite style element of mine is to combine SETQ assignments into a single SETQ with indentation. This clearly sets large variable assignment sections of code apart from other sections. The most frequent use of this programming style will appear when initializing variables. In the earlier days of AutoLISP the combination of multiple SETQ expressions into a single one actually was a time saver since the SETQ subr did not need to be evaluated for each assignment. Under current machine structures with the optimized environment of Visual LISP such considerations are no longer valid. Instead it is simply a style issue. Having all the variable assignments stand out is easier to read, once you get used to it.
The naming of variables and functions is something that can be subject to a variety of styles. I guess you could say it is variable in nature. When coding something quick and dirty it is easiest to use local variables with short names such as TMP and PNT followed by a number. But when writing code for distribution to a large user base one should use a registered prefix (Autodesk Developer Network members can apply for a registered prefix name) or just a common prefix for your application. If you create an application called “Better Than Sliced Bread” you could start all function names with BTSB- and all global symbols with BTSB_. The use of the dash and underscore for functions and variable names is a style thing too. It makes reading the code at a later time much easier.
Comment styles vary greatly from one programmer to another. I once worked at a place where all comments had to follow specific formats in the code otherwise the “code police” would reject the source code for publication. Sounds extreme but when 400+ programmers are contributing to a massive project it only makes sense. Half of the 400+ were engaged in debugging and they needed a break. Standardized comments helped them read through code looking for possible problems in the logical flow. Visual LISP has two different comment formats available. The most commonly used is the semicolon. When the semicolon is seen in a physical line of code the semicolon and all remaining characters are considered comments. The Visual LISP editor shows comment text with a background of grey making them very easy to spot. The other comment format supported by Visual LISP starts with the characters semicolon and vertical line. Comment code can then be included for multiple lines (or just inside a single physical line) until the reverse character sequence of a vertical line and a semicolon are encountered. Commented code is much easier to read when you are not the author or it is something you wrote a while back. What ever style you use, you will eventually come to appreciate well commented code.
The use of upper and lower case characters in Visual LISP is an element of style. I tend to use lower case for anything in the code that is a common function or subr. Variable and function symbols are generally a mixture of upper and lower case to promote readability. To illustrate the variable name for the length of a steel bar might be written out as BarLength. Whatever approach one takes with names and the use of upper and lower case, the code is much more readable when it is applied consistently. Characters are nothing more than symbols that the eye recognizes thus using “tmp” and “TMP” in the same code is a bit more difficult to spot even though Visual LISP would consider them to be the same thing.
Style is cool and these style points are just my own comments about how I like to code. Feel free to use the same style or invent your own. Part of the fun in Visual LISP is that you can do just that. If you want to write code even an expert would have difficulty reading then use variable names like $a and XX, put all your code on one physical line, remove all comments, and hide the function definitions in the middle. I don’t recommend that style of coding because after all, someday you or someone else will have to maintain that program for minor changes to the environment (AutoCAD).
Keep on programmin’