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:

Disadvantage:

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:

Disadvantage:


[Contents]
This document was translated by troff2html v0.21 on July 18, 1997.