Coding and Documentation Conventions

Introduction

This document describes the conventions to be observed when writing code and documentation for the Decision Procedure Toolkit.

General Conventions

File names

File names may contain only letters, digits and underscores. No spaces or special characters may appear in a file name.

Line width

No line may by longer than 80 characters.

Indentation

Any sensible indentation scheme that clearly reflects the structure of the document is acceptable.

Indentation Width

When not otherwise determined, say by a wish to align certain features in a document, the width of an indentation shall be 2 columns.

Tabs

Using tabs is discouraged, but if used they must be understood to mean “move to the next column that is a multiple of 8”.

File headings

All files begin with two comments. The first comment includes just the svn Id keyword. This first comment may violate the 80 column maximum rule. The second comment is a one-line summary of the purpose of the file. For example, this file begins with the following comments:

⟨!-- $Id: conventions.html 1785 2007-09-28 ... agoel3 $ --⟩
⟨!-- Description of project coding and documentation standards. --⟩

The form of the one-line summary comment may be different from the others to ensure that it is seen by the ocamldoc tool. More specific requirements on the form of the one-line summary comment will given below where relevant.

Boilerplate

Immediately after the file heading, each file should include the copyright notice and the Apache 2.0 license boilerplate, as described in the appendix to the Apache 2.0 license. For example, the next few lines of this file are as follows:

⟨!-- 
  Copyright 2007 Intel Corporation

  Licensed under the Apache License, Version 2.0 (the "License"); you
  may not use this file except in compliance with the License.  ...

OCaml Coding Conventions

File names

In addition to the restrictions that apply to all file names, no upper case letters may appear in the name of an OCaml source file. Note that even though OCaml module names correspond to file names, and that OCaml module names must begin with a capital letter, it is not necessary (nor permitted) to capitalize the first letter of an OCaml file name. Multiple words in a multi-word file name should be separated by an “_”. A file name might look like this:

multi_word_module.ml

Module names

Module names in OCaml code begin, as required, with a capital letter. Other letters should be lower case. Subsequent words in a multi-word module name should be be separated by an “_” and should start with a lower-case letter. A module name might look like this:

Multi_word_module

Module type names

Each word in an OCaml module type name should begin, as required, with a capital letter. Other letters should be lower case. Multiple words in a multi-word module type name should not be separated by an “_”. A module type name might look like this:

MultiWordModuleType

Class and class type names

Class and class type names in OCaml code begin, as required, with a lower case letter. Other letters should be lower case. Subsequent words in a multi-word class or class type name should be be separated by an “_” and should start with a lower-case letter. A class or class type name might look like this:

multi_word_class

Type constructor names

Each word in an OCaml type constructor name should begin, as required, with a capital letter. Other letters should be lower case. Multiple words in a multi-word type constructor name should not be separated by an “_”. A type constructor name might look like this:

MultiWordTypeConstructor

Exception names

Exception names begin, as required, with an upper case letter. Other letters should be in lower case. Multiple words in a multi-word exception name should be separated by an “_”. A multi-word exception name might look like this:

Multi_word_exception

Other names

All other names begin, as required, with a lower case letter. Other letters should also be lower case. Multiple words in a multi-word name should be separated by an “_”. A multi-word name might look like this:

multi_word

OCaml Documentation Conventions

OCamlDoc

All types and values in interface files are to be documented using OCamlDoc comments.

File headings

For OCaml interface files, or implementation files that have no corresponding interface file, the one-line summary comment should be an OCamlDoc comment. The following is an example heading from an OCaml interface file. Note the extra “*” on the second comment.

(*  $Id: vec.mli 1785 2007-09-28 ... agoel3 $ *)
(** Dynamically resizable arrays. *)

Module comments

When documenting a module, module signature, or functor, place the header comment before the definition, like this:

(** Description of ModuleType *)
module type ModuleType = sig
   ...
end

Include comments

When documenting a module inclusion, place the header comment before the inclusion, like this:

(** Bar is a foo kind of thing. *)
include Foo

Type comments

When documenting a type, place the comment before the type signature, like this:

(** Description of type t *)
type t

Value and method comments

When documenting a value or method, place the header comment after the signature, like this:

val v: t
  (** Description of value v *)

method m: t
  (** Description of method m *)

OCamlLex and OCamlYacc Conventions

File Headings

The first two heading comments of an OCamlYacc file should be given as OCamlYacc comments. The second, file summary, comment should be given as an OCamlDoc comment inside the initial OCaml code block. This allows OCamlDoc to extract the file summary comment. The standard boilerplate should then appear as an OCaml comment. For example, an OCamlYacc file might begin as follows:

/* $Id: smtlib_grammar.mly 1785 2007-09-28 ... agoel3 $ */
%{
  (** Parser for SMT-LIB theory, logic, and benchmark files. *)
  
  (* Copyright 2007 ...

The heading comments in OCamlLex files should be given as OCamlLex comments. A separate .mli file can, and should, be specified for the OCamlLex file with appropriate OCamlDoc comments included.

Terminal Names

Terminal (token) names begin, as required, with an upper case letter. All other letters in a terminal name should also be upper case. Multiple words in a multi-word terminal name should be separated by an “_”. A multi-word terminal name might look like this:

MULTI_WORD_TERMINAL

Other names

All other names begin, as required, with a lower case letter. Other letters should also be lower case. Multiple words in a multi-word name should be separated by an “_”. A multi-word name might look like this:

multi_word

HTML Conventions

Document type and style

All web pages should be in strict compliance with the HTML 4.01 document type definition and use the OCamlDoc style sheet. For example, the first real information in this file, immediately after the standard boilerplate comment, is as follows:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" 
 "http://www.w3.org/TR/html4/strict.dtd">
<HTML>
<HEAD>
<LINK rel="stylesheet" href="ocamldoc_html/style.css" type="text/css">

Tag capitalization

HTML tags are capitalized, like this “<HEAD>”.

Address block

All web pages should end with a copyright notice in an address block. For example, the concluding lines of this file are as follows:

<ADDRESS>
&copy; 2007 Intel Corporation
</ADDRESS>
</BODY>
</HTML>

Hosted by the ^* web site.
^*Other names and brands may be claimed as the property of others.