CodingStandards

== Coding Standards ==

Larceny is built on a variety of systems and runs on a variety of hardware and software architectures. Its source code was written by a variety of programmers working at different times and places, using a variety of editors and other tools.

To keep Larceny's source code executable and readable, programmers are expected to follow the coding practices described below.

Formatting

Line length should be limited to 79 characters or less. Lines longer than 79 characters may be tolerated in source files that are generated by automated tools or written by programmers who are not Larceny developers.

Tab characters should not appear in Scheme code. (There is no standard interpretation of tab characters, so their presence in a file makes the indentation depend on the software used to view the file.) In assembly code, a single tab character is permitted at the beginning of a line, provided all lines in the file that begin with whitespace begin with a single tab character. Tab characters are permitted at the beginning of a line of C or C++ or C# source code, provided each tab character can be replaced by four spaces without changing the intended appearance of the code.

Scheme code should be indented following the pattern established by Larceny's pretty printer. Exception: When a procedure call or binding of the form (operator argument1 argument2 ...) is divided into two or more lines, with a line break between operator and argument1, then operator and argument1 should be aligned vertically; Larceny's pretty printer currently outputs an extra space before argument1, which Will regards as a bug.

In files that contain Scheme code, block and top-level comments describe the file, divide the source file into sections, and describe code that follows the comment. Each line of a block or top-level comment begins with one to three semicolons (one or three is preferred). Each block or top-level comment should be separated from the following code by a single blank line.

Comment lines that appear within the source code of a procedure or expression describe code that follows the comment. They begin with either a single semicolon or with two semicolons. They are normally preceded and followed by a single blank line, although the blank lines may be omitted for minor comments within straightforward code.

Comments that describe a single line of code (to their left) begin with a single semicolon. In a sequence of lines with such comments, the comments should be aligned on the left or on the right. (Tab characters are especially pernicious to the left of the semicolon that begins a comment of this type, since minor changes to the code will wreak editor-dependent havoc on the alignment of comments.)

If a comment describes improvements that should be made, the comment should begin with FIXME.

Portability

Larceny has been cross-compiled using a variety of systems: MacScheme, Gambit, Chez Scheme, Petite Chez, MzScheme, and Larceny itself. To make this work, all code that is executed on the host system during a system build has been written in moderately portable R5RS Scheme, using only the extensions provided by Larceny's compatibility files and certain other extensions that are described in this section. All code that is compiled during a system build, even if it is not executed during the system build, has been written using the lexical syntax of R5RS Scheme plus certain extensions that are described below.

Most R5RS systems permit a more liberal lexical syntax than is required by the R5RS, and we have been relying on some of those extensions. This is a problem for R6RS conversion, since the R6RS does not allow extensions.

During our transition to R6RS lexical syntax, we should limit ourselves to the lexical syntax of the 5.94 draft with the following extensions and omissions.

Extensions to R6RS syntax that are used in some Larceny source code, but should be removed over time:

• certain nonstandard peculiar identifiers (-- -1+ 1+ 1-)
• leading . or @ or +: or -: in symbols
• backslashes in strings before characters that don't have to be escaped

Extensions to R6RS syntax that are used in .fasl files, but should be removed over time:

• vertical bar as a in symbols
• backslashes in strings before characters that don't have to be escaped

Extensions to R6RS syntax that are used and will continue to be used in .fasl files:

• #!fasl #!unspecified #!undefined
• #^B #^C #^F #^P #^G randomness

R6RS syntax that should not be used in Larceny code until MzScheme supports it:

• #!r6rs
• #\alarm #\esc #\delete
• hexadecimal syntax within symbols (e.g. \x3bb;)
• hexadecimal syntax within strings (e.g. "\x3bb;")
• hexadecimal syntax for characters (e.g. #\x3bb)

All Larceny code should be written to compile correctly regardless of whether the host system is case-sensitive. Exception: The Unicode library, and other files that implement features that will be new in the R6RS, can assume case-sensitivity.

Subversion

When adding a text or source file to Larceny, the following properties should be set:

svn propset svn:eol-style native 
svn propset svn:keywords "Author Date Id Revision" 

A file of Scheme source code should begin with a block comment that looks approximately like this:

; Copyright 1998 Lars T Hansen
;
; $Id$
;
; Larceny library -- system parameter abstraction.

The copyright notice, if present, should be the original copyright notice or a notice approved by the copyright holder. (Obviously, the copyright holder must have given us permission to use the code in Larceny, either by granting us specific permission or by granting permission to a class of people and projects that includes the Larceny project.) The modification history can be described underneath the copyright notice. Nowadays, we can let Subversion record the modifications that have occurred since the code was added to Larceny.