LFE Style Guide

4 Documentation

4.1 Document everything

You should use document strings on all visible functions to explain how to use your code.

Unless some bit of code is painfully self-explanatory, document it with a documentation string (also known as docstring).

Documentation strings are destined to be read by the programmers who use your code. Documentation strings are where you should document your API. They should describe how to use the code (including what pitfalls to avoid), as opposed to how the code works (and where more work is needed), which is what you'll put in comments.

Supply a documentation string when defining top-level functions, types, classes, variables and macros. Generally, add a documentation string wherever the language allows.

For functions, the docstring should describe the function's contract: what the function does, what the arguments mean, what values are returned, what conditions the function can signal. It should be expressed at the appropriate level of abstraction, explaining the intended meaning rather than, say, just the syntax. In documentation strings, capitalize the names of Lisp symbols, such as function arguments. For example:

(defun get-area (length width)
  "This function calculates the area of a rectangle.

  The value of LENGTH should be an integer. The value of WIDTH should be an
  integer."
  ...)

A long docstring may usefully begin with a short, single-sentence summary, followed by the larger body of the docstring.

When you fix a bug, consider whether what the fixed code does is obviously correct or not; if not, you must add a comment explaining the reason for the code in terms of fixing the bug. Adding the bug number, if any, is also recommended.

4.2 Comment Semicolons

Comments are explanations to the future maintainers of the code. Even if you're the only person who will ever see and touch the code, even if you're either immortal and never going to quit, or unconcerned with what happens after you leave (and have your code self-destruct in such an eventuality), you may find it useful to comment your code. Indeed, by the time you revisit your code, weeks, months or years later, you will find yourself a different person from the one who wrote it, and you will be grateful to that previous self for making the code readable.

You must comment anything complicated so that the next developer can understand what's going on. (Again, the "hit by a bus" principle.)

Also use comments as a way to guide those who read the code, so they know what to find where.

File headers and important comments that apply to large sections of code in a source file should begin with four semicolons ;;;;.
You should use three semicolons ;;; to begin comments that apply to just one top-level form or small group of top-level forms.
Inside a top-level form, you should use two semicolons ;; to begin a comment if it appears between lines.
You should use one semicolon ; if it is a parenthetical remark and occurs at the end of a line. You should use spaces to separate the comment from the code it refers to so the comment stands out. You should try to vertically align consecutive related end-of-line comments.

Example:

;;;; Great module description
;;;; ...
(defmodule great-module
  (export
    (some-useful-function 1)))

...

;;; Comment about function
(defun some-useful-function (useful-argument)
  (another-function useful-argument)           ; Comment at end of line
  (yet-another-fucntion)                       ; Another one for this line
  ;; Comment about the next chunk of code at the same level of indentation
  ...)
...

For all semicolon comments, you should include a space between the semicolon and the text of the comment.

4.3 Grammar and Punctuation

When a comment is a full sentence, you should capitalize the initial letter of the first word and end the comment with a period. In general, you should use correct punctuation.

4.4 Attention Required

You should follow the convention of using TODO OR XXX comments for code requiring special attention. For code using unobvious forms, you must include a comment.

For comments requiring special attention, such as incomplete code, todo items, questions, breakage, and danger, include a TODO OR XXX comment indicating the type of problem, its nature, and any notes on how it may be addressed.

The comments begin with TODO OR XXX in all capital letters, followed by the name, e-mail address, or other identifier of the person with the best context about the problem referenced by the TODO. The main purpose is to have a consistent TODO that can be searched to find out how to get more details upon request. A TODO is not a commitment that the person referenced will fix the problem. Thus when you create a TODO, it is almost always your name that is given.

When signing comments, you should use your username or full email address, which ever most readily identifies you. If using github, you can use your github username preceded by the "@" sign. Do not just initials of your name.

Examples:

;; XXX (oubiwann@cogitat.io): Refactor to provide a better API.

Be specific when indicating times or software releases in a TODO comment and use YYYY-MM-DD format for dates to make automated processing of such dates easier, e.g., 2038-01-20 for the end of the 32-bit signed time_t.

;; TODO (@rvirding): Remove this code after release 1.7 or before
;; 2012-11-30.

For code that uses unobvious forms to accomplish a task, you should include a comment stating the purpose of the form and the task it accomplishes.

4.5 Domain-Specific Languages

You should design your Domain Specific Language to be easy to read and understand by people familiar with the domain.

You must properly document all your Domain Specific Language.

Sometimes, your DSL is designed for terseness. In that case, it is important to document what each program does, if it's not painfully obvious from the context.

Notably, when you use regular expressions (e.g. with the re module), you should always put in a comment (usually a two-semicolon comment on the previous line) explaining, at least basically, what the regular expression does, or what the purpose of using it is. The comment need not spell out every bit of the syntax, but it should be possible for someone to follow the logic of the code without actually parsing the regular expression.