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.
- Indentation
- Comment conventions
- Naming conventions
- Global variables
- Documentation conventions
- Copyright and acknowledgements
- Proofreading
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"
Itcl comment
conventions are described elsewhere. However, in general,
comments should follow the guidelines below.
All programming languages have a global namespace. In itcl, it's class
names, global variables, and procedure names. Choose names carefully.
In particular,
- All global variables
in Tycho should begin
with "ty" and should be documented. The documentation is
temporarily being collected in the file "doc"
in the main Tycho directory.
- All procedure names should begin with "ty" unless they already
existed in pigi, in which case they should begin with "ptk" and
should be backward compatible.
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 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.
The Tycho documentation layout and conventions are discussed in $TYCHO/doc/documentation.html
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:
- An uncopyrighted program (public domain) is used either verbatim
or as inspiration. In this case, it is essential to acknowledge the
author and institution originating the code, but this has no effect
on our copyright policy.
- A copylefted program (under the Gnu public license) is used
as inspiration. If there is no verbatim code used, then it
is sufficient (and necessary) to acknowledge the author and
institution.
- A copylefted program or portion of a program is used verbatim.
This will place the entire Tycho program under the Gnu public license,
and therefore should be done only with good reason. However, we are
not averse to doing this. If you include copylefted code,
be sure to identify every line of code that is borrowed in this
way. This will allow us (or someone else) to later rewrite this
code and liberate Tycho from the copyleft.
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.
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.
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
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