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. Java exceptions conventions
  6. Documentation conventions
  7. Copyright and acknowledgements
  8. 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, In Itcl, 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"
In Java, you can often use the + operator to concatenate Strings together:
	return "This is a really " +
	       "long string";

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, class names, and procedure names are in the global namespace. Choose names carefully.

    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.

    Method and variable names that are protected or private a leading underscore "_". (i.e. _protectedMethod(), _privateMethod().

    Method names should have internal capitalization and start with a lower case letter (i.e. aPublicMethod()).

    If possible, variables should not use internal capitalization, unless the name is long. This makes it easier to distinguish between methods and variables. However, avoiding capitalization in variable names is up to the implementer.

    Method and variable names should avoid using underscores internally.

    Global Variables

    Global variables are almost entirely unnecessary in Itcl. If you need a global variable, use a "common" variable in a class.

    Documentation conventions

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

    Java exceptions conventions

    Java exception classes that are part of the pt package in $TYCHO/java/pt should follow these conventions.
  • All pt package exceptions should extend PtolemyException so that we can catch these exceptions at runtime. By having a hierarchy of exceptions, we can differentiate between generic Java exceptions and exceptions that the pt package has thrown.
  • Exceptions should be defined in the same package as the classes that throw them. The exceptions in java.lang follow this convention.
  • In Java, most Exceptions have two constructors, a nullary constructor and a constructor that takes a String detail argument.
    In the Ptolemy II kernel, Exceptions have these two constructors as well as constructors that take one or two NamedObj arguments. The purpose of the NamedObj arguments is to provide a uniform interface and look and feel to exception messages.
  • When throwing an exception, it is best if the detail message is a complete sentence that includes a string that describes to object that caused the exception. For example
    throw MyException(this, "The list already contains an element named `" + 
    	getElementName() +"'.");
    
  • 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: 1995-%Q% The Tycho interface to SCCS takes care of interpreting the %Q%.

    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 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 GOT IT WORKING.

    Tycho Home Page


    Copyright © 1995-1998, The Regents of the University of California. All rights reserved.
    Last updated: 05/22/98, comments to: eal@eecs.berkeley.edu