Tcl Coding Conventions

A.7 Code Layout

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

Vertical Spacing

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.

Horizontal Spacing

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

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.

Comments

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