Programming Style for Tycho

The following programming style will be followed in the Tycho project. Please submit comments or suggestions to eal@eecs.berkeley.edu.

  1. Indentation
  2. Comment conventions
  3. Naming conventions
  4. Global variables
  5. Documentation conventions
  6. Copyright and acknowledgements
  7. Proofreading

Indentation

Tabs are 8 characters. Do not override this in your text editor. Nested statements should be indented 4 characters, as in:
itcl_class MyClass {
    inherit MyParent
    constructor {config} {
        One line constructor command
    }
}
Closing brackets should be on a line by themselves, aligned with the beginning of the line that contains the open bracket.

Long lines (which are common especially for Tk commands) should be broken up into many small lines. Continuation lines are indented by 8 characters, as in

        $prefix.m.edit.menu add command \
                -label "Select All" \
                -underline 0 \
                -accelerator "C-/" \
                -command "$this selectall"
Notice that the line breaks are carefully chosen so that the options are easy to identify. Avoid the following variant:
        $prefix.m.edit.menu add command \
                -label "Select All" \
                -underline 0 -accelerator "C-/" \
                -command "$this selectall"
Glancing at this, it is easy to miss the -accelerator option.

If you have a long puts statement, you can use backslashes to make the text more readable. Note that each backslash introduces a space in the output.

        puts "This is a long line \
             that extends over a few\n\
             lines"

Comment conventions

Itcl comment conventions are described elsewhere. However, in general, comments should follow the guidelines below.
  • Comments should include honest information about the limitations of the object definition.
  • Comments should be complete sentences and complete thoughts.
  • Naming conventions

    All programming languages have a global namespace. In itcl, it's class names, global variables, and procedure names. Choose names carefully. In particular, In itcl, there is no limit to name sizes (as it should be). Do not hesitate to use long names.

    When naming objects, use automatic naming as much as possible. For any itcl class that does not define a top-level window, the syntax is:

    Classname #auto ?options?
    
    If the class defines a top-level window (i.e. it eventually inherits the TopLevel class ), then you should use the syntax
    Classname [::tycho::autoname .classname] ?options?
    
    The autoname procedure is defined in Tycho and returns a class name that is constructed by appending to the single argument an underscore and an integer that ensures that the name will be unique.

    Global Variables

    Global variables are almost entirely unnecessary in itcl. If you need a global variable, use a "common" variable in a class. Note that at least one instance of the class must have been created for the common variable to exist. (Apparently, it can have been deleted as well).

    There appears to be one circumstance in which global variables are needed. A Tk checkbutton object generally has a global variable associated with it. There appears to be no way to use a common variable for this (that I have found). The name of the global variable should begin with "ty", and its existence should be documented, as explained above.

    Documentation conventions

    The Tycho documentation layout and conventions are discussed in $TYCHO/doc/documentation.html

    Copyright and Acknowledgements

    We would prefer to be able to release Tycho with the standard UC Berkeley copyright, which allows for subsequent commercialization. However, this is a large project, and we should use existing code as much as possible. The following scenarios are possible: In all cases, any foreign code that you use should be carefully read and tested. Yes, it should be read! Preferably, it should be reformatted to fit our programming style, but if it is a large piece of code, it is probably not worth doing. We will need to devise a scheme to avoid confusing the automatic documentation generator. If it is Tcl/Tk code, it must be ported to Tk 4.0 (a nontrivial task). If it is not itcl code, it should be carefully searched for namespace violations.

    If your file is based on a file that has non-UC Berkeley copyrights, then you should be sure to include the copyrights.

    SCCS and copyrights

    Currently we are using the %Q% sccs directive to adjust the copyright dates automatically. The copyright should have %Q% as the ending date of the copyright: 1990-%Q% If you are setting up a new directory, then you should do:
    sccs admin -fq1995 SCCS
    
    to set the Q variable in the SCCS directory. Note that after doing the sccs admin command, 'make sources' will check out all the files in that directory. If you are adding a new file, you can do:
    sccs admin -fq1995 SCCS mynewfile.cc
    
    If your file is a rewrite of a previously copyrighted file from UC Berkeley, then you should include the date from that file.

    Copyright for Itcl files

    The Itcl template file contains the appropriate copyright to be used for Itcl files at UC Berkeley. Other sites may want to substitute in their own template. The Itcl editor has a file template menu choice that will insert the Itcl template file

    Proofreading

    Software has become a publication medium. People will read your code. Your name is on it, so you want to be proud of it. It seems that most people stop working on the code when it "works." This is like stopping work on a paper when what it says is correct, and not worrying at all about how it is said. PROOFREAD YOUR CODE AFTER YOU'VE GOTTEN IT WORKING.

    Tycho Home Page


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