Script Formatting

To Maya, it truly does not matter whether the script looks pretty. The MEL interpreter really doesn t care whether there are carriage returns and tab-overs in the file. In fact, the script could be one long line, with the only spaces those dictated by syntax rules and semicolons separating the various commands. For the human mind, however, this is a most difficult way to work.

Putting some care into the formatting of our script helps the author during the creation and debugging phases, and aids in any further modification by others. There are some basic elements added to a well structured script that greatly increase its readability to all those who might need to look at the source code.

Whitespace

The most basic thing one can do to aid in the readability of a script is use whitespace . To use an art metaphor, whitespace is the negative space around the text of a script. That is to say that while looking at an image, much can be discerned simply by looking at the area around a drawing. With text it s much the same. By separating different groups of commands together by adding in extra carriage returns, the script becomes much more legible, and makes it easier to find specific sections. In Examples 5.3 and 5.4, we have written the same code, which simply takes the translation attributes and rearranges their values, twice, once with a simple extra carriage return, which adds much to the code fragment s readability and visual cohesiveness.

Example 5.3: Lack of whitespace makes code difficult to read.

 $x = `getAttr object.tx`;     $y = `getAttr object.ty`;     $z = `getAttr object.tz`;     setAttr object.tz $x;     setAttr object.ty $z;     setAttr object.tx $y; 

Example 5.4: Simple carriage returns add visual clarity to code.

 $x = `getAttr object.tx`;     $y = `getAttr object.ty`;     $z = `getAttr object.tz`;     setAttr object.tz $x;     setAttr object.ty $z;     setAttr object.tx $y; 

Another useful tool for structuring whitespace is indentation. Most often done with tabs, many text editors allow the number of spaces contained in a tab to be user configurable. In this book, we use four, but each user can set the tab size to his or her liking. Indentation is used to control the visual flow of a script, easily identifying nested command groups and loops . In Examples 5.5 and 5.6, we again take the same code and use whitespacing to add legibility and visual organization to our code.

Example 5.5: Code without tabs blends together.

 if ($printVal)     for ($each in $list) {     print $each;     print "\n"; } 

Example 5.6: Tabs separate out different command groups.

 if ($printVal)         for ($each in $list)             {                 print $each;                 print "\n";             } 

By simply adding a few spaces, indentations, and extra carriage returns, our code goes from being something that looks like a meaningless listing of code to a program with structure and thought. While it might seem like a minor thing to put such craftsmanship in the structure of text that will more than likely be seen by no one other than the author and the MEL interpreter, using whitespace well adds an ease-of-use factor to the process of writing and debugging scripts.

Comments

Comments are both one of the most useful and most underused aspects of scripting. The irony of this underuse is that whenever the concept of commenting scripts is spoken of in the communities that scripters frequent, there is nearly universal agreement that commenting is a good thing. The basic definition of a comment is a segment of text that is ignored by the interpreter. Comments are created by prefacing any text with two forward slashes , // . Once a line has been commented, all text to the right of those slashes will be ignored; both styles are seen in Example 5.7.

Example 5.7: Adding single line comments.

  // The following gets the translate x value of $obj  float $x = `getAttr ($obj + ".tx")`;     float $x=`getAttr ($obj+".tx")`;  //gets the $obj tx value  

MEL also supports multi-line comments that allow a scripter to add large amounts of commented text to a script. Multi-line comments are extraordinarily useful for adding headers to scripts, which we will cover in just a moment. To comment out blocks of text, enclose the text with two markers. The opening marker is a forward slash followed by an asterisk, /*; to close a comment, use the reverse, an asterisk followed by a slash, */. Example 5.8 provides a demonstration of the multi-line comment in use.

Example 5.8: Multiline comments are often used at the beginning of files or to explain complicated sections of code.

 /*  The following switch-case looks at input from the global   procedure passPolyInfo.  Because of this make sure   passPolyInfo.mel is included with any distribution of this   file  .     */ 

Note that while single-line comments are valid within expressions (see Chapter 10, Creating Tools in Maya), multi-line comments are not. Either keep expression comments brief or begin each comment line with a //.

Comments of both types are useful for debugging, by essentially removing a line or entire blocks of text from a script without actually deleting that text. Comments are also essential for scripts that are created in a group environment, to explain what each procedure and action s intended purpose is. Finally, because MEL is based on the English language, if a script is to be used in an environment where another language is prevalent , putting explanations in that language, even re-writing pseudo-code in that language, can be useful. Because MEL commands are mostly composed of words or word fragments in the English language, it is easier for an English speaker to decipher what is going on at each point in the script.

Those scripters working in a text editor that supports color coding are well advised to add comments as a drastically different color , which makes code with comments highly readable at a moment s glance.

Header Information

At the very top of a script file should be the header information. While each production environment will most likely have requirements and guidelines as to what information needs to be included, and in what order that information should be presented, there is some information that every file should contain. Enclosing this information as a multi-line comment prevents it from being executed and highly visible.

Any header should, at minimum contain the following: author s name , date of last modification and by whom, the version of Maya the script was written for, and how the script is used. Other common information is a script version number, a version history, as well as extensive instructions, and the author s e-mail address or Web homepage. A common header is seen in Example 5.9.

Example 5.9: A sample header

 /*  myScript.mel   author: John Doe ([e-mail])   version: v1.01a   last mod: 05-16-2002 18:34 (Doe)   usage: myScript  name number  function: myScript prints  name  to the script   editor  number  times  .  ver. history: v0.9   printed "John Doe" 20 times   v1.0   added support for name entry   v1.1   added support for number entry   v1.1a  fixed bug that would accidentally   kill a users pet goldfish  */ 

Obviously, that last bug fix is most likely not going to creep into any scripts, but it proves as a good case example. By keeping a log of what changes have been made to a script, a user can intelligently make decisions as to whether he needs or wants to get the latest version of a script. In addition, please note the use of whitespace and formatting of the header. More than any other part of a script, the header needs to be easily readable by any user, even those not versed in MEL.

Any header of a script meant for public distribution should contain a legal disclaimer in the form of an End User License Agreement (EULA) . The EULA is meant to protect a script s author if, by using the script, an artist deletes all of his models, formats the hard drive, and e- mails his credit card number to every hacker site known to humankind. Actually, not that last part ”that s pretty much illegal. The scripts on the CD-ROM accompanying this book all contain EULAs, which can be used as the basis for the EULA of any script.