Commenting Conventions

High Maintenance:

Use the '#' for all comments

Example: Code with errors

 # proc computeArea { height width }
 #  calculates the area of a rectangle
 #   height :	height of rectangle
 #   width  :	width of rectangle
 proc computeArea {height width } {
   if {($height < 0) || ($width < 0)} {
     puts "dimensions must be positive"		# Don't do this
     return 0;
     }
   return [expr $height * $width]
  }

Advantage:

• The # requires low processing overhead.

Disadvantage:

• Comments on a line with code may be errors (as shown above)

• No differentiation between in-code comments, and proc header comments.

  ---

  Low Maintenance:

Precede comments with ;# as a habit.

Use different comment conventions for code comments and header comments.

Example: Same code without errors

 ;#:: proc computeArea { height width }
 ;#::  calculates the area of a rectangle
 ;#:   height :	height of rectangle
 ;#:   width  :	width of rectangle
 proc computeArea {height width } {
   if {($height < 0) || ($width < 0)} {
     puts "dimensions must be positive"		;# Do do this
     return 0;
     }
   return [expr $height * $width]
   }

Advantage:

• Less likely to create errors by placing a comment character where an argument (rather than a command) could go.

• Header comments can be extracted from code with grep to create a reference document.

Disadvantage:

• Processing the ";" requires processor overhead.

  ---