Guidelines for Contributors

For now, the M.I.T. AI Lab group reserves the right to decide which contributions merit inclusion in the core system and the distribution. This page describes how to write good code that can be easily incorporated into the production CL-HTTP. This document will evolve as people make suggestions about how to make it better.

Code Submission

Submit Atomic Patches: Submit a file with just the relevant changes required to add the functionality to the system and with comments indicating the system version used and the source file containing any modified definition. When changing existing source code, put all the changed code in a different type face (e.g., bold and leave the old code commented out, and in this way, make it much easier for people to identify exactly what you have changed.

Export Interfaces: Export only those symbols that constitute the defined interface for the functionality.

Documentation: Write documentation strings for all exported symbols and consider documenting important interface definitions so that the documentation tools can find your definitions and describe their usage.

Release Notes and Instructions: Provide a one paragraph abstract and an extended summary for use in the release notes and server documentation where applicable. The summary should be in HTML and contain the following information:

1. Concise description of the functionality.
2. Steps for installing or starting up the facility.
3. Current status and future plans.
4. Author and point of contact for further information.

Efficiency

CL-HTTP makes an effort to maximize efficiency (it should do more) so that the speed of the server does not become a reason for people not to use it. At the same time, we want a clean set of abstractions that can be easily customized to meet user needs. So, there is a trade-off between efficiency and abstraction. In general, one should start by developing good abstractions and then optimize as necessary to achieve acceptable performance. Typically, you want to optimize only the critical path.

Here are some ways to write efficient code:

Minimize consing at all times by using destructive operations.

Use the dynamic extent declaration for consing that can be done on the stack.

Use generic functions sparingly at those points where the abstraction is needed, and otherwise, use functions and fast accessors.

Inline critical-path functions. This is a way to conserve abstraction while gaining efficiency. You need to beware of over inlining and thus bloating the working set.

Declare numerical computations to avoid doing bignum arithmetic when possible.

A more extended set of suggestions is available in efficiency heuristics.

Abstraction

CL-HTTP is intended to be a toolkit for Web hacking. Although the ability to write response functions in Common Lisp will increase productivity, it is helpful to have a set of extensible abstractions to minimize code duplication and provide well-crafted operators. Thus, the way Cl-HTTP can distinguish itself from other server offerings will be by providing a rational set of abstractions or toolkit and making it easy to extend or customize the behavior of the server.

Here are some hints about how to write well-abstracted code:

Use the existing operator.

Propose an extension to the existing operator.

Make a function or method do only one well-defined task. The goal is to avoid repeating code fragments with close functionality. Whenever a piece of code is used more than once, or is likely to be used more than once, make it a first-class operator.

Give each operator, variable or class a spelled-out mnemonic name so that others will find the abstraction and use it. Recycle the vocabulary found in existing operators when naming new ones. Operators should contain verb forms describing the action or function they do while arguments should have names that describe the datatype which a caller should pass to them.

All external symbol and any major internal operators should have document strings. These should explain what the operator does and what its arguments are. As becomes obvious from the Online Help Facility the combination of the documentation string with the function and argument names are the documentation.

When an operator gets too many parameterizing arguments, consider breaking it up into subfunctions.

Whenever an operator's source definition exceeds a screenful, break it down into a combination of suboperators.

Always use CLOS objects as your datastructure. Forget about defstruct, except when speed is essential!

Provide a generic function for each toplevel operation on a class, while using functions or inline functions within according to speed requirements.

Use local functions (e.g., FLET, LABELS, MACROLET) to capture abstractions within a definition and to avoid repeated code.