Ken Clowes (kclowes@ee.ryerson.ca)
Developing software requires some discipline. One component of this discipline that is often underestimated by beginners is the adherence to some set of general principles for organizing and writing source code. Many of these principles are are sufficiently general that they should be applied to all software irrespective of the programming language. For example, the principles described here can be applied to C, Assembler, Matlab, Java, C++, VHDL, Maple, tcl, Perl, shell scripts and others.
The source code for programming projects should always be organized and written with the future tasks of testing, debugging and maintenance (possibly by others) in mind. The coding standards described here deal with the larger issues that make these tasks easier. The most fundamental principle is consistency--whatever detailed coding standards you adopt, you should always follow them consistently.
The rest of this document expands on the basic principles outlined below:
In these cases, the public comments could, for example, be specially designed so that a ``man page'' or HTML description could be generated automatically from the source code public comments.
For example, the source code for a package of Java classes should contain public comments that can be used to automatically generate all the documentation a user of the package needs to exploit its features.
Some other languages such as C, C++ and elisp also have tools or conventions that allow the automatic generation of user documentation.
If the language does not have such tools, the programmer should
develop their own standards for clearly identifying comments that are
public. For example, one convention that I use for assembly language
programming is to start all lines that are public comments with
``;;''.
Public documentation should be accurate, but terse. If more lengthy descriptions are required, a separate user manual or on-line help interface should be designed and their existence should be stated in the public documentation.
It is also recommended that the public documentation of interfaces be written before actually coding the implementation. Specifying the interface focuses the mind on the essentials and allows the designer to review the interface looking for inconsistencies or ambiguities before committing it to code.
Since the reader of these comments is assumed to be competent in the programming language, obvious comments that clutter the code and insult the reader's intelligence should be avoided. For example, code like:
i++; /* Increment i */
should be avoided.
Often, no private comments are required at all in well written programs. The use of descriptive names is also a great help. Indeed, Rob Pike states:
Basically, avoid comments. If your code needs a comment to be understood, it would be better to rewrite it so it's easier to understand. Rob Pike[Pik]
Avoiding comments completely, however, is sometimes too drastic a measure. The programmer should use common sense and consider the needs of the potential reader. If it is expected that the reader is a seasoned expert in the language, it may be appropriate to have minimal or even no private comments at all. However, if you think the reader may have only a smattering of expertise, more detailed private comments are reasonable. I find this to be especially true for scripting languages. For example, I sometimes write perl scripts but I am not an expert in the language and I insert private comments to remind myself what bizarre language feature I am using. Of course, a perl guru may find such comments superfluous and annoying.
Another situation in which detailed implementation comments are often appropriate is source code that is meant for pedagogical use by people just learning the language.
Numeric and string constants should be given symbolic names; this is far preferable than embedding ``magic'' numbers or messages in the source code.
The README file should be a pure text file.
The Makefile's default target should create the project's implementation from source code. Other common targets include:
You say toe-may-toes
I say toe-mah-toes
Let's call the whole thing off.--Ira Gershwin (lyrics) and George Gershwin (music)
Source code should be formatted so that visual clues (such as indentation or vertical white space) aid in understanding the organization and logical flow of the implementation.
Different organizations and individuals may have specific detailed conventions that they follow and it is not our intention to stipulate any particular standard (which risks starting religious wars over minor details). However, as a general principle, I do prefer:
These rules ensure that you can always examine the source code on a dumb terminal and that you can embed it in an e-mail message easily.
With the emacs editor, there are special editing modes for almost all programming languages. To avoid tabs and limit line length, you can use the auto-fill mode and set indent-tabs-mode to nil.
I have written more detailed descriptions of coding standards for C[Clob] and assembler[Cloa]
file:~kclowes/public/CodingStds/CodingStdAsm.ps
C Coding Standards.
file: CodingStdC.ps.
The Practice of Programming.
Addison-Wesley, Reading, Massachusetts, 1999.
267 pages.
Notes on Programming in C.
5 pages.
This document was generated using the LaTeX2HTML translator Version 98.1p1 release (March 2nd, 1998)
Copyright © 1993, 1994, 1995, 1996, 1997, Nikos Drakos, Computer Based Learning Unit, University of Leeds.
The command line arguments were:
latex2html -split 1 CodingStdGen.tex.
The translation was initiated by Ken Clowes on 2000-11-11