|
_This document is still under construction._ IntroductionThis page describes the coding conventions used by the Zuzu Curl project. Some of the conventions are based on those used internally at Curl Inc. File Organization- Directory layout and naming should match that of the components.
| Extension | File types | | .curl | Curl applets | | .mcurl | Curl manifests | | .xcurl | Curl scripts | | .scurl | Other Curl code |
- Every Curl package should be placed in its own directory. The main file for the package should be named load.scurl.
- Manifests must only delegate to manifests in subdirectories or sibling directories. (Cyclical manifest delegation is not permitted by the Curl language.)
- Tests should be organized under the tests/ directory, with subdirectories for each package to be tested.
- Generally there should be one class per file, which should be given the same name as the class. Exceptions may be made for sets of related small classes or for auxiliary classes used exclusively by the code in the file.
Versioning- All Curl applets, packages, manifests and scripts should be declared to run under the full range of supported versions for the project, which is currently 6.0 and 7.0, unless the component is specifically intended for a specific version. For example:
{curl 6.0, 7.0 applet}- All packages should declare a version, starting with 0.1. Version 1.0 should be the first public release version, after which API changes should be backward compatible.
- Component versions should be changed according the following rules. Changing the first component of the version (e.g., 1.7 to 2.0) should indicate major API changes. Changing the second component (e.g., 1.7 to 1.8) should indicate minor API changes. Changing the third component (e.g. 1.7 to 1.7.1) is used for patches that do not change the API. These rules do no apply to pre 1.0, which can be expected to change significantly.
Formatting- All source files should begin with a comment indicating who is the primary maintainer, in the form:
|| Maintained by: <e-mail-address> - Lines should not exceed 80 columns.
- Restrict code to ASCII unless code is specifically meant to support non English users.
- Except for non-structural markup forms like {bold ...} or {link ...}, every close curly brace '}' should be placed on the same line or column as its corresponding open curly '{'. For example:
{do
{output "hi"}
}- Class members should be ordered as follows:
- fields
- class variables
- constructors/factories
- getters/setters/methods grouped by the base class in which they are first defined with the most general base class (e.g. Object) first, and the class being defined last.
- private getters/setters/methods should be grouped together at the bottom.
Within groupings, class members should be defined alphabetically.
- Enclose curlies around global and class variables and constants but not local variables and constants. This makes globals visually distinct and also makes it easier to search for all globals just by looking for "{let".
- Do not use curlies around field declarations or set statements.
- Except when you want to display a value, avoid top-level statements in applets because any value returned by a function at the top level will be displayed by the applet. Instead put code inside a top-level {do ...} block.
NamingThese naming rules conform to those described in the Curl Developer's Guide. - All packages and manifests should be named. Applet and script names are optional.
- Component names (package, manifest, etc.) should be all in uppercase with dot's to indicate heirarchy. Component names should start with the name of the manifest in which they are declared followed by "." and an uppdercase identifier for the component. For example, the package ZUZU.TEST.BASE is listed in the ZUZU.TEST manifest.
- Test packages containing tests for a given library should begin with the name of the library name and add .TESTS. For instance, test packages for ZUZU.TEST all begin with ZUZU.TEST.TESTS. Typically test packages containing unit tests for a given package in the library will append the package name. For instance, the test package for ZUZU.TEST.BASE is named ZUZU.TEST.TESTS.BASE.
- Type names should be written using CamelCase (aka CrazyCaps). Type names should form a noun phrase.
- All other names should be lowercase with words separated by '-'. Familiar acronyms may be written using uppercase if that will aid readability. Constants should not be written using uppercase as is common in C code.
- Method and proc names should form verb phrases.
- Field, option, variable and constant names should form noun phrases.
- Names for boolean values should end with '?'. Functions/methods returning a boolean value should have names ending in '?' only if the returned value makes sense with the name.
Use of new language features- This project is currently intended to support the versions 6.0 and later of the Curl API. Therefore, any use of Curl RTE features not present in 6.0 must be conditionalized on the API version. In general, use of new features is discouraged but not forbidden.
- When using api-version-switch to conditionalize use of a new feature, explicitly list the old versions, and place code for the new feature in the else clause instead of listing the new version. Otherwise we will have to add a new version to all such switch statements everytime a new version of the Curl API is released. For example:
{api-version-switch
case "6.0" do
{old-technique}
else
{new-technique}
}Documentation- Write doc-strings for any binding that is accessible outside of its package.
- Test doc-strings by doing a doc deployment before checking in.
Source Control- Commit unrelated changes in separate check-ins when possible. This makes the check-ins easier to understand and easier to undo if necessary.
- Commit changes in dependency order. For instance, if you add a new class and a subclass in parallel check-ins, check-in the superclass first.
- Avoid changes that break working test cases and especially avoid changes that don't compile. If you want to checkpoint code that does not yet compile, comment out the broken parts before checking in.
|
Sign in to add a comment
