Tcl Coding Conventions

A.9 Tcl Style

The following conventions define additional standards of programming style:

Comments: Insufficiently commented code is unacceptable.

Procedure Length: Procedures should have a reasonably small number of lines, less than 50 if possible.

Case Statement: Do not use the case keyword. Use switch instead.

expr and Control Flow Commands: Do not use expr in commands such as if, for or while except to convert a variable from one format to another:

CORRECT:

                if {$id != 0} {

CORRECT:

                if {[expr $id] != 0} {

INCORRECT:

                if {[expr $id != 0]} {

expr and incr: Do not use expr to increment or decrement the value of a variable. Use incr instead.

CORRECT:

                incr index

CORRECT:

                incr index -4

INCORRECT:

                set index [expr $index + 1]

wtxPath and wtxHostType: Use these routines when developing tools for Tornado. With no arguments, wtxPath returns the value of the environment variable WIND_BASE with a "/" appended. With an argument list, the result of wtxPath is an absolute path rooted in WIND_BASE with each argument as a directory segment. Use this command in Tornado tools to read resource files. The wtxHostType call returns the host-type string for the current process (the environment variable WIND_HOST_TYPE. if properly set, has the same value). For example:

source [wtxPath host resource tcl]wtxcore.tcl 
set backenddir [wtxPath host [wtxHostType] lib backend]*

catch Command: The catch command is very useful to intercept errors raised by underlying procedures so that a script does not abort prematurely. However, use the catch command with caution. It can obscure the real source of a problem, thus causing errors that are particularly hard to diagnose. In particular, do not use catch to capture the return value of a command without testing it. Note also that if the intercepted error cannot be handled, the error must be resubmitted exactly as it was received (or translated to one of the defined errors in the current procedure):

CORRECT:

                if [catch "dataFetch $list" result] { 
                        if {$result == "known problem"} { 
                            specialCaseHandle 
                        } else { 
                            error $result 
                        }

INCORRECT:

                catch "dataFetch $list" result

if then else Statement: In an if command, you may omit the keyword then before the first command body; but do not omit else if there is a second command body.

CORRECT:

                if {$id != 0} { 
                        ... 
                    } else { 
                        ... 
                    }

INCORRECT:

                if {$id !=0} then { 
                        ... 
                    } { 
                        ... 
                    }

Return Values: Tcl procedures only return strings; whatever meaning the string has (a list for instance) is up to the application. Therefore each constant value that a procedure can return must be described in the procedure documentation, in the RETURNS: block. If a complex element is returned, provide a complete description of the element layout. Do not use the return statement to indicate that an abnormal situation has occurred; use the error statement in that situation.

The following illustrates a complex return value consisting of a description:

# Return a list of 11 items: vxTicks taskId status priority pc 
# sp errno timeout entry priNormal name 
 
return [concat [lrange $tiList 0 1] [lrange $tiList 3 end]]

The following illustrates and simple return value:

# This code checks whether the VxMP component is installed: 
 
if [catch "wtxSymFind -name smObjPoolMinusOne" result] { 
    if {[wtxErrorName $result] == "SYMTBL_SYMBOL_NOT_FOUND"} { 
        return -1       # VxMP is not installed 
    } else { 
        error $result 
    } 
} else { 
    return 0             # VxMP is installed 
}

Error Conditions: The Tcl error command raises an error condition that can be trapped by the catch command. If not caught, an error condition terminates script execution. For example:

if {$defaultTaskId == 0} { 
    error "No default task has been established." 
}

Because every error message and error code must be described in the procedure header in the ERRORS: block, it is sometimes useful to call error in order to replace an underlying error message with an error expressed in terms directly relevant to the current procedure. For example:

if [catch "wtxObjModuleLoad $periodModule" status] { 
    error "Cannot add period support module to Target ($status)" 
}