Google Common Lisp Style Guide

This style guide contains many details that are initially hidden from view. They are marked by the triangle icon, which you see here on your left. Click it now. You should see "Hooray" appear below.

Each guideline's level of importance is indicated by use of the following keywords and phrases, adapted from RFC 2119.

There are cases where transgression of some of these rules is useful or even necessary. In some cases, you must seek permission or obtain forgiveness from the proper people.

You MUST follow conventions. They are not optional.

Fix old code as you go.

There are many topics for additional standardization not covered by current version of this document, but deferred to future versions.

There are some basic principles for team software development that every developer must keep in mind. Whenever the detailed guidelines are inadequate, confusing or contradictory, refer back to these principles for guidance:

• Every developer's code must be easy for another developer to read, understand, and modify — even if the first developer isn't around to explain it. (This is the "hit by a truck" principle.)
• Everybody's code should look the same. Ideally, there should be no way to look at lines of code and recognize it as "Fred's code" by its style.
• Be precise.
• Be concise.
• KISS — Keep It Simple, Stupid.
• Use the smallest hammer for the job.
• Use common sense.
• Keep related code together. Minimize the amount of jumping around someone has to do to understand an area of code.

When making decisions about how to write a given piece of code, aim for the following -ilities in this priority order:

• Usability by the customer
• Debuggability/Testability
• Readability/Comprehensibility
• Extensibility/Modifiability
• Efficiency (of the Lisp code at runtime)

To build code that is robust and maintainable, it matters a lot how the code is divided into components, how these components communicate, how changes propagate as they evolve, and more importantly how the programmers who develop these components communicate as these components evolve.

Often, the smallest hammer is to use an existing library. Or one that doesn't exist yet. In such cases, you are encouraged to use or develop such a library, but you must take appropriate precautions.

If you write a general-purpose library, or modify an existing open-source library, you are encouraged to publish the result separate from your main project and then have your project import it like any other open-source library.

Development process is outside the scope of this document. However, developers should remember at least these bits: get reviewed, write tests, eliminate warnings, run tests, avoid mass-changes.

You must use correct spelling in your comments, and most importantly in your identifiers.

When several correct spellings exist (including American vs English), and there isn't a consensus amongst developers as which to use, you should choose the shorter spelling.

You must use only common and domain-specific abbreviations, and must be consistent with these abbreviations. You may abbreviate lexical variables of limited scope in order to avoid overly-long symbol names.

You should format source code so that no line is longer than 100 characters.

Indent your code the way a properly configured GNU Emacs does.

Maintain a consistent indentation style throughout a project.

Indent carefully to make the code easier to understand.

You should include a description at the top of each source file.

You should include neither authorship nor copyright information in a source file.

Vertical white space: one blank line between top-level forms.

Horizontal white space: none around parentheses. No tabs.

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

You must use the appropriate number of semicolons to introduce comments.

You should punctuate documentation correctly.

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

You should document DSLs and any terse program in a DSL.

You should use lower case. You should follow the rules for Spelling and Abbreviations You should follow punctuation conventions.

Name your variables according to their intent, not their content.

Name globals according to convention.

Names of predicate functions and variables end with a "P".

You should not include a library or package name as a prefix within the name of symbols.

Use packages appropriately.

You should avoid side-effects when they are not necessary.

You should favor iteration over recursion.

Use special variables sparingly.

Be consistent in assignment forms.

You must make proper usage of assertions and conditions.

If you know the type of something, you should make it explicit in order to enable compile-time and run-time sanity-checking.

Use CLOS appropriately.

Use macros when appropriate, which is often. Define macros when appropriate, which is seldom.

When using EVAL-WHEN, you should almost always use all of (:compile-toplevel :load-toplevel :execute).

You should use #. sparingly, and you must avoid read-time side-effects.

You must not use EVAL at runtime.

You must not use INTERN or UNINTERN at runtime.

Appropriately use or avoid using NIL.

You must select proper data representation. You must not abuse the LIST data structure.

You should use the appropriate representation for product types.

Use the appropriate functions when manipulating lists.

You should use arrays rather than lists where random access matters.

You should only use lists as sets for very small lists.

You must use proper defining forms for constant values.

You should make proper use of &OPTIONAL and &KEY arguments. You should not use &AUX arguments.

Use the appropriate conditional form.

You should use the appropriate predicates when comparing objects.

Use the appropriate form for iteration.

Use the appropriate I/O functions.

You should avoid unnecessary allocation of memory.

You must only use faster unsafe operations when there is a clear performance need and you can document why it's correct.

You should only use DYNAMIC-EXTENT where it matters for performance, and you can document why it is correct.

You should use REDUCE instead of APPLY where appropriate.

You should not use NCONC; you should use APPEND instead, or better data structures.

You should usually refer to a function as #'FUN rather than 'FUN.

Common Lisp pathnames are tricky. Be aware of pitfalls. Use UIOP.

You must be careful when using a SATISFIES clause in a type specifier.