Tycho File Headers

Itcl files written for Tycho should follow a certain style in the headers.

  1. Example Header
  2. Doc Tags
  3. The Order of Elements
This page discusses file headers, Itcl file bodies are discussed elsewhere.

Example Header

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.

Below is a sample header:

# A circular list data structure.
#
# @Author: Edward A. Lee
#
# @Version: %W%	%G%
#
# @Copyright (c) 1995-%Q% The Regents of the University of California.
# All rights reserved.
# 
# Permission is hereby granted, without written agreement and without
# license or royalty fees, to use, copy, modify, and distribute this
# software and its documentation for any purpose, provided that the
# above copyright notice and the following two paragraphs appear in all
# copies of this software.
# 
# IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
# FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
# ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF
# THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF
# SUCH DAMAGE.
# 
# THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
# INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
# MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE
# PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF
# CALIFORNIA HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES,
# ENHANCEMENTS, OR MODIFICATIONS.
# 
# 						PT_COPYRIGHT_VERSION_2
# 						COPYRIGHTENDKEY
##########################################################################

Doc Tags

The header contains doc tags to identify different parts of the header. Doc tags are more fully described in the tydoc documentation, but briefly, a doc tag is a keyword, such as @Author that is at the start of a comment. Doc tags are case-insensitive, and my be pluralized. The trailing colon ":" is optional, and it is not part of the doc tag. If the trailing colon is present, the tydoc removes it from the comment.

The order of elements

The file header consists of the following elements, separated by blank lines. Note that the order of tags should strictly followed for consistency between files.
  1. A one line description of what the file does
  2. @Author: - The primary Author(s) of the file. If you have more than one author, use @Authors:. With multiple authors, the last two names should be separated by and
    	# @Authors: Author One, Author Two and Author Three
    	
    Please try to follow the existing naming convention that people use for themselves, some people use a middle initial, some don't.
  3. @Contributor: - (Optional) People who have contributed to this file. If there are more than one contributor, you can pluralize this.
  4. @Version: - The Version control information for this file. The version control system can automatically update special characters at file check in time, so that the file can contain the date and version number. Currently, we are using SCCS at UC Berkeley. If you use the string
    	# @Version: %W% %G%
    	
    Then SCCS will convert this to the file name, version number and date:
    	# @Version: @(#)Tycho.tcl	1.37	6/14/96
    	
    Note that there is a space between %W% %G%, not a tab.
  5. @Copyright - The Copyright for this file. Usually @Copyright is not followed by a colon. The issue of copyrights is fairly tricky, if you are an employee of UC Berkeley, you should include the copyright as it is printed above. Note that the special symbol is expanded at our site at UC Berkeley to be the current year. The Tycho style guide contains more information about copyrights.

Tycho Home Page


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