By Ray Johnson
This is a manual for people who are developing Tcl code for Wish or any other Tcl application. It describes a set of conventions for writing code and the associated test scripts. There are three reasons for the conventions. First, the conventions ensure that certain important things get done; for example, every procedure must have documentation that describes each of its arguments and its result, and there must exist test scripts that exercise every line of code. Second, the conventions guarantee that all of the Tcl and Tk code has a uniform style. This makes it easier for us to use, read, and maintain each other’s code. Third, the conventions help to avoid some common mistakes by prohibiting error-prone constructs such as building lists by hand instead of using the list building procedures.
This document is based heavily on the Tcl/Tk Engineering Manual written by John Ousterhout. John’s engineering manual specified the style of the C code used in the implementation of Tcl/Tk and many of its extensions. The manual is very valuable to the development of Tcl/Tk and is an important reason why Tcl is a relatively easy system to maintain. Deciding any style standard involves making trade-offs that are usually subjective. This standard was created in an iterative process involving the Tcl/Tk group at Sun Laboratories. I don’t claim that these conventions are the best possible ones, but the exact conventions don’t really make that much difference. The most important thing is that we all do things the same way.
Please write your code so that it conforms to the conventions from the very start. For example, don’t write comment-free code on the assumption that you’ll go back and put the comments in later once the code is working. This simply won’t happen. Regardless of how good your intentions are, when it comes time to go back and put in the comments you’ll find that you have a dozen more important things to do; as the body of uncommented code builds up, it will be harder and harder to work up the energy to go back and fix it all. One of the fundamental rules of software is that its structure only gets worse over time; if you don’t build it right to begin with, it will never get that way later.
The rest of this document consists of 8 major parts. We start with Section 2 which discusses executable files. Section 3 discusses the overall structure of packages and namespaces. Section 4 describes the structure of a Tcl code file and how to write procedure headers. Section 5 desribes the Tcl naming conventions. Section 6 presents low-level coding conventions, such as how to indent and where to put curly braces. Section 7 contains a collection of rules and suggestions for writing comments. Section 8 describes how to write and maintain test suites. Section 9 contains a few miscellaneous topics, such as keeping a change log.
Read More/Download
This is a manual for people who are developing Tcl code for Wish or any other Tcl application. It describes a set of conventions for writing code and the associated test scripts. There are three reasons for the conventions. First, the conventions ensure that certain important things get done; for example, every procedure must have documentation that describes each of its arguments and its result, and there must exist test scripts that exercise every line of code. Second, the conventions guarantee that all of the Tcl and Tk code has a uniform style. This makes it easier for us to use, read, and maintain each other’s code. Third, the conventions help to avoid some common mistakes by prohibiting error-prone constructs such as building lists by hand instead of using the list building procedures.
This document is based heavily on the Tcl/Tk Engineering Manual written by John Ousterhout. John’s engineering manual specified the style of the C code used in the implementation of Tcl/Tk and many of its extensions. The manual is very valuable to the development of Tcl/Tk and is an important reason why Tcl is a relatively easy system to maintain. Deciding any style standard involves making trade-offs that are usually subjective. This standard was created in an iterative process involving the Tcl/Tk group at Sun Laboratories. I don’t claim that these conventions are the best possible ones, but the exact conventions don’t really make that much difference. The most important thing is that we all do things the same way.
Please write your code so that it conforms to the conventions from the very start. For example, don’t write comment-free code on the assumption that you’ll go back and put the comments in later once the code is working. This simply won’t happen. Regardless of how good your intentions are, when it comes time to go back and put in the comments you’ll find that you have a dozen more important things to do; as the body of uncommented code builds up, it will be harder and harder to work up the energy to go back and fix it all. One of the fundamental rules of software is that its structure only gets worse over time; if you don’t build it right to begin with, it will never get that way later.
The rest of this document consists of 8 major parts. We start with Section 2 which discusses executable files. Section 3 discusses the overall structure of packages and namespaces. Section 4 describes the structure of a Tcl code file and how to write procedure headers. Section 5 desribes the Tcl naming conventions. Section 6 presents low-level coding conventions, such as how to indent and where to put curly braces. Section 7 contains a collection of rules and suggestions for writing comments. Section 8 describes how to write and maintain test suites. Section 9 contains a few miscellaneous topics, such as keeping a change log.
Read More/Download
