Itcl File Body Conventions

Itcl files written for Tycho should follow a certain style in body. The file header is discussed elsewhere.

  1. Itcl comment conventions
  2. Itcl class comments
  3. Itcl class declaration body
  4. Itcl class definition bodies

Itcl comment conventions

In general, comments should follow the conventions described in the Tycho style guide.

The tydoc system automatically generates html documentation from the source code file, so the comments should follow the tydoc comment format conventions. The Itcl template file contains a template of an itcl file with the appropriate copyright and comment formats. The Itcl editor has a file template menu choice that will insert the Itcl template file.

The Itcl editor contains a menu choice that will create a Itcl body template that is useful for creating definition bodies.

The order of elements

The Itcl file body consists of the following element. Note that the order of tags should strictly followed for consistency between files.

Itcl class comments

The class comment describes the class. Below is an example class comment:
######################################################################
#### MyClass
# This class does very little, but here is an example
# <tcl><pre>
# ::tycho::MyClass
# </pre></tcl>
#
::tycho::MyClass {
Class comments have the following elements:
  1. A line of comment characters that starts the class comment.
    	######################################################################
    	
  2. Four comment characters, followed by the class name. This tells the reader what class is being defined, which is useful if the actual comment is long.
    	#### MyClass
    	
  3. The actual comment, which is usually multiple lines. A line that consists of only a hashmark and white space will get expanded into a paragraph break by tydoc.
    	# This class does very little, but here is an example
    	
  4. An embedded tcl code example.
    	# <pre><tcl>
    	# ::tycho::MyClass
    	# </pre></tcl>
    	
  5. The last line of the class comment, located right before the actual class definition should be a blank comment line, consisting of only a single hashmark.
    	#
    	
  6. The actual class declaration should include the namespace.
    	 ::tycho::MyClass {
    	

Itcl class declaration body

In itcl, the class declaration body defines the interface to the class. The actual definition can be either included in the class declaration body, or after the class declaration body in a series of body statements. However, the Tycho convention require that methods and procedures that are longer than one line be in separate body statements after the class body itself. This makes the file more readable.

See the Itcl template file for a complete example of a Itcl class body. Below we discuss the major elements of a class body.

  1. If the class inherits from another class, then the inherits line should be the first line of the class body.
  2. The constructor and destructor declarations should come first. These may or may not have a one line comment.
  3. Each declaration in the class body should have a one line description, and each declaration should not exceed one line, unless the body of the declaration is itself one line long. For example:
    	# Call exit
    	method myMethod {a b} {
    		exit 
    	}
    	
  4. The remaining declarations in the class body should be in the following order:
    1. options
    2. public methods
    3. public procs
    4. protected methods
    5. protected procs
    6. protected variables
    7. private methods
    8. private procs
    9. private variables
  5. Each section should be start with a comment that describes that section. For example the public methods section should start with:
        ###################################################################
        ####                         public methods                    ####
    
    

Itcl class definition bodies

The Tycho convention dictates that methods and procedures that have bodies longer than one line be placed in body definitions after the class declaration.
  • Class definition bodies have formats just like Itcl class comments.
  • Class definition bodies should be in the same order as they were declared in the class declaration body.
  • Here's an example class definition body:
    #######################################################################
    #### NameA
    # Description.
    #
    body ::tycho::ClassName::publicMethodA {} {
    }
    

    Tycho Home Page


    Copyright © 1996, The Regents of the University of California. All rights reserved.
    Last updated: 96/12/16, comments to: tycho@eecs.berkeley.edu