This section defines the Wind River Systems standard for all C and Tcl code and for the accompanying documentation included in source code. The conventions are intended, in part, to encourage higher quality code; every source module is required to have certain essential documentation, and the code and documentation is required to be in a format that has been found to be readable and accessible.

The conventions are also intended to provide a level of uniformity in the code produced by different programmers. Uniformity allows programmers to work on code written by others with less overhead in adjusting to stylistic differences. Also it allows automated processing of the source; tools can be written to generate reference entries, module summaries, change reports, and so on.

These conventions are divided into the following categories:

• Module Layout

• Procedure Layout

• Code outside of procedure

• Code Layout

• Naming Conventions

• Style

A module is any unit of code that resides in a single Tcl file. The conventions in this section define the standard module heading that must come at the beginning of every Tcl module following the standard file heading. The module heading consists of the blocks described below; the blocks are separated by one or more blank lines.

After the modification history and before the first function or executable code of the module, the following sections are included in the following order, if appropriate:

• General Module Documentation:  The module documentation is a block of single-line Tcl comments beginning by the keyword DESCRIPTION and consisting of a complete description of the overall module purpose and function, especially the external interface. The description includes the heading RESOURCE FILES followed by a list of relevant Tcl files sourced inside the file.

• Globals:  The globals block consists of a one-line Tcl comment containing the word globals followed by one or more Tcl declarations, one per line. This block groups together all declarations in the module that are intended to be visible outside the module.

The format of these blocks is shown in the following example (which also includes the Tcl version of the file heading):

Example B-1:  Tcl File and Module Headings

# Browser.tcl - Browser Tcl implementation file 
# 
# Copyright 1994-1995 Wind River Systems, Inc. 
# 
# modification history 
# -------------------- 
# 02b,30oct95,jco  added About menu and source browser.tcl in .wind. 
# 02a,02sep95,pad  fixed communications loss with license daemon (SPR #1234). 
# 01c,05mar95,jcf  upgraded spy dialog 
# 01b,08feb95,p_m  take care of loadFlags in wtxObjModuleInfoGet. 
# 01a,06dec94,c_s  written. 
#  
# DESCRIPTION 
# This module is the Tcl code for the browser. It creates the main window and 
# initializes the objects in it, such as the task list and memory charts. 
# 
# RESOURCE FILES 
# wpwr/host/resource/tcl/shelbrws.tcl 
# wpwr/host/resource/tcl/app-config/Browser/*.tcl 
# ... 
#*/ 
 
# globals 
 
set browserUpdate         0         ;# no auto update by default

The following conventions define the standard layout for every procedure in a module.

Each procedure is preceded by the procedure documentation, a series of Tcl comments that includes the following blocks. The documentation contains no blank lines, but each block is delimited with a line containing a single pound symbol (#) in the first column.

• Banner:  A Tcl comment that consists of 78 pound symbols (#) across the page.

• Title:  One line containing the routine name followed by a short, one-line description. The routine name in the title must match the declared routine name. This line becomes the title of automatically generated reference entries and indexes.

• Description:  A full description of what the routine does and how to use it.

• Synopsis:  The word SYNOPSIS: followed by a the synopsis of the procedure--its name and parameter list between .tS and .tE macros. Optional parameters are shown in square brackets. A variable list of arguments is represented by three dots (...).

• Parameters:  For each parameter, the .IP macro followed by the parameter name on one line, followed by its complete description on the next line. Include the default value and domain of definition in each parameter description.

• Returns:  The word RETURNS: followed by a description of the possible explicit result values of the subroutine (that is, values returned with the Tcl return command).

RETURNS: 
A list of 11 items: vxTicks taskId status priority pc sp errno 
timeout entry priNormal name

If the return value is meaningless enter N/A:

RETURNS: N/A

• Errors:  The word ERRORS: followed by all the error messages or error code (or both, if necessary) raised in the procedure by the Tcl error command.

ERRORS: 
"Cannot find symbol in symbol table"

If no error statement is invoked in the procedure, enter N/A.

ERRORS: N/A

The procedure documentation ends with an empty Tcl comment starting in column one.

The procedure declaration follows the procedure heading and is separated from the documentation block by a single blank line. The format of the procedure and parameter declarations is shown in VxWorks Programmer's Guide: Coding Conventions.

The following is an example of a standard procedure layout.

Example B-2:  Standard Tcl Procedure Layout

##################################################################### 
# 
# browse - browse an object, given its ID 
# 
# This routine is bound to the "Show" button, and is invoked when 
# that button is clicked.  If the argument (the contents of... 
# 
# SYNOPSIS 
# .tS 
# browse [objAddr | symbol | &symbol] 
# .tE 
# 
# PARAMETERS 
# .IP <objAddr> 
# the address of an object to browse 
# .IP <symbol> 
# a symbolic address whose contents is the address of 
# an object to browse 
# .IP <&symbol> 
# a symbolic address that is the address of an object to browse 
# 
# RETURNS: N/A 
# 
# ERRORS: N/A 
#

 
proc browse {args} { 
    ...  
}

Tcl allows code that is not in a procedure. This code is interpreted immediately when the file is read by the Tcl interpreter. Aside from the global-variable initialization done in the globals block near the top of the file, collect all such material at the bottom of the file.

However, it improves clarity--when possible--to collect any initialization code in an initialization procedure, leaving only a single call to that procedure at the bottom of the file. This is especially true for dialog creation and initialization, and more generally for all commands related to graphic objects.

Tcl code outside procedures must also have a documentation heading, including the following blocks:

• Banner:   A Tcl comment that consists of 78 pound symbols (#) across the page.

• Title:  One line containing the file name followed by a short, one-line description. The file name in the title must match the file name in the file heading.

• Description:  A description of the out-of-procedure code.

The following is a sample heading for Tcl code outside all procedures.

Example B-3:  Heading for Out-of-Procedure Tcl Code

##################################################################### 
# 01Spy.tcl - Initialization code 
# 
# This code is executed when the file is sourced. It executes the module 
# entry routine which does all the necessary initialization to get a 
# runnable spy utility. 
#  
 
# Call the entry point for the module 
 
spyInit

Include only one declaration per line. Declarations are indented in accordance with Indentation, and begin at the current indentation level. The remainder of this section describes the declaration formats for variables and procedures.

For global variables, the Tcl set command appears first on the line, separated from the identifier by a tab character. Complete the declaration with a meaningful comment at the end of the same line. Variables, values, and comments should be aligned, as in the following example:

set     rootMemNBytes     0  ;# memory for TCB and root stack 
set     rootTaskId        0  ;# root task ID 
set     symSortByName    1  ;# boolean for alphabetical sort

The procedure name and list of parameters appear on the first line, followed by the opening curly brace. The declarations of global variables used inside the procedure begin on the next line, one on each separate line. The rest of the procedure code begins after a blank line. For example:

proc lstFind {list node} { 
    global firstNode 
    global lastNode 
 
    ... 
}

The maximum length for any line of code is 80 characters. If more than 80 characters are required, use the backslash character to continue on the next line.

The rest of this section describes conventions for the graphic layout of Tcl code, covering the following elements:

• vertical spacing

• horizontal spacing

• indentation

• comments

• Use blank lines to make code more readable and to group logically related sections of code together. Put a blank line before and after comment lines.

• Do not put more than one declaration on a line. Each variable and function argument must be declared on a separate line.

• Do not put more than one statement on a line. The only exceptions are:

• A for statement where the initial, conditional, and loop statements can be written on a single line:

for {set i 0} {$i < 10} {incr i 3} {

• A switch statement whose actions are short and nearly identical (see the switch statement format in Indentation).

The if statement is not an exception. The conditionally executed statement always goes on a separate line from the conditional expression:

if {$i > $count} { 
    set i $count 
}

• Opening braces ({), defining a command body, are always on the same line as the command itself.

• Closing braces (}) and switch patterns always have their own line.

• Put spaces around binary operators. Put spaces before an open parenthesis, open brace and open square bracket if it follows a command or assignment statement. For example:

set status [fooGet $foo [expr $i + 3] $value] 
if {&value & &mask} {

• Line up continuation lines with the part of the preceding line they continue:

set a [expr ($b + $c) * \ 
            ($d + $e)] 
set status [fooList $foo $a $b $c \ 
                    $d $e] 
if {($a == $b) && \ 
    ($c == $d)} { 
    ... 
}

• Indentation levels are every four characters (columns 1, 5, 9, 13, ).

• The module and procedure headings and the procedure declarations start in column one.

• The closing brace of a command body is always aligned on the same column as the command it is related to:

while { condition }{ 
    statements 
} 
 
foreach i $elem { 
    statements 
}

• Add one more indentation level after any of the following:

• procedure declarations

• conditionals (see below)

• looping constructs

• switch statements

• switch patterns

• The else of a conditional is on the same line as the closing brace of the first command body. It is followed by the opening brace of the second command body. Thus the form of the conditional is:

if { condition } { 
    statements 
} else { 
    statements 
}

The form of the conditional statement with an elseif is:

if { condition } { 
    statements 
} elseif { condition } { 
    statements 
} else { 
    statements 
}

• The general form of the switch statement is:

switch [flags] value { 
    a   { 
        statements 
        } 
    b   { 
        statements 
        } 
    default { 
        statements 
        } 
}

If the actions are very short and nearly identical in all cases, an alternate form of the switch statement is acceptable:

switch [flags] value { 
    a   {set x $aVar} 
    b   {set x $bVar} 
    c   {set x $cVar} 
}

• Comments have the same indentation level as the section of code to which they refer (see Comments).

• Opening body braces ({) have no specific indentation; they follow the command on the same line.

• Place comments within code so that they precede the section of code to which they refer and have the same level of indentation. Separate such comments from the code by a single blank line.

• Begin single-line comments with the pound symbol as in the following:

# This is the correct format for a single-line comment 
 
set foo 0

• Multi-line comments have each line beginning with the pound symbol as in the example below. Do not use a backslash to continue a comment across lines.

# This is the CORRECT format for a multiline comment 
# in a section of code. 
 
set foo 0 
 
# This is the INCORRECT format for a multiline comment \ 
in a section of code. 
 
set foo 0

• Comments on global variables appear on the same line as the variable declaration, using the semicolon (;) character:

set day    night    ;# This is a global variable

The following conventions define the standards for naming modules, routines and variables. The purpose of these conventions is uniformity and readability of code.

• When creating names, remember that code is written once but read many times. Make names meaningful and readable. Avoid obscure abbreviations.

• Names of routines and variables are composed of upper- and lowercase characters and no underbars. Capitalize each "word" except the first:

aVariableName

• Every module has a short prefix (two to five characters). The prefix is attached to the module name and to all externally available procedures and variables. (Names that are not available externally need not follow this convention.)

  fooLib.tcl		module name
  fooObjFind		procedure name
  fooCount		variable name

• Names of procedures follow the module-noun-verb rule. Start the procedure name with the module prefix, followed by the noun or object that the procedure manipulates. Conclude the name with the verb or action that the procedure performs:

  fooObjFind		foo - object - find
  sysNvRamGet		system - non volatile RAM - get
  taskInfoGet		task - info - get

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)" 
}