Style Guides

With regard to indentation standards, I strongly feel that publically available code should be looked upon as a published document.

There should be no spelling errors.

The comments should be syntactically correct

The comments should produce readable documentation when tools like javadoc are run

There should be a common documented style for each of the languages. Ideally, the style between languages should be as similar as possible.

The style should be checked by automatic tools.

Style guidelines are a fact of life in industry, they are almost always set by someone else.

Choosing a common style can be very controversial. The most important thing is that the members of a development team all agree on the same style.

Java Coding Style

The Ptolemy II Coding style is documented in $PTII/doc/coding/style.htm

To set up Emacs to follow the Ptolemy II coding style, download ptjavastyle.el and follow the instructions at the top

The Sun Java Coding Conventions are documented at http://java.sun.com/docs/codeconv/

Java tools

Emacs: GNU Emacs includes cc-mode which has a reasonable Java format
jindent: jindent is a shell script that invokes uses Emacs to indent java files. jindent is part of Ptolemy II, but is available as a separate download via http://ptolemy.eecs.berkeley.edu/java/jindent.htm
chkjava: chkjava is a shell script that checks for common problems in Java source files. chkjava is part of Ptolemy II, it can be viewed at $PTII/util/testsuite/chkjava
ptspell: ptspell is a short shell script that uses a local dictionary with the Unix spell command to find misspellings. ptspell is part of Ptolemy II, but it can be used on any document, not just Java. ptspell can be found at $PTII/util/testsuite/ptspell

C++ Coding Style

The GNU tool gindent supports three common styles:

The GNU style
The Kernighan & Ritchie style
The original Berkeley Style
possibility.com C++ Style Guide Discussion

We are open to proposals for a standard CHESS C++ style. Ideally the style would be one of the above styles with few if any modifications.

Code Documentation

Ideally, C++ code would use an embedded documentation tool that is similar to javadoc.

Doc++, at http://www.zib.de/Visual/software/doc++/index.html might be of use.

Doxygen

C++ Indenting Tools

GNU Indent - C only

faqs.org C-C++ Beautifiers - Interesting ideas about verifying that an indenter or beautifier does not change the code

astyle Indents C/C++/Java. Supports ansi, gnu, K&R etc.

BCPP - Indents C/C++ code

Metropolis II includes metro/util/testsuite/cindent, a script that uses Emacs to indent C++ code.

Filenaming conventions

Below are some subtle issues involved in naming files

NT has a rather strange way of handling case in file names. It appears that file names are case insensitive, but case is preserved. Thus, under NT, you may have problems if a directory contains a file or subdirectory named Foo and a file or subdirectory named foo. Note that NT also has problems with DOS special names like com1, lpt1, or aux

Under NT filenames with spaces are a fact of life. Scripts should be written and tested with filenames with spaces.

GNU make looks for makefile before looking for Makefile. If a software package standardizes on Makefile, and someone accidentally introduces a file named makefile, then the accidentally introduced file is read and the proper Makefile is ignored.
Thus, it is better to standardize on makefile. Also the NT filenaming issues can also cause problems

You are not logged in