- -Revision 1.28 -
- - - -Robert Brown - - - François-René Rideau - - - - In memoriam Dan Weinreb - - --Patterns mean "I have run out of language." — Rich Hickey -
- - -- Each style point has a summary for which additional information is available - by toggling the accompanying arrow button that looks this way: - . - You may toggle all summaries with the big arrow button: -
-| - | - |
| - | - |
| - | - |
| - | - |
| - | - |
| - | - |
| - | - |
| - | - |
| - | - |
| - | - |
| - | - |
- Common Lisp is a powerful multiparadigm programming language. - With great power comes great responsibility. -
-- This guide recommends formatting and stylistic choices - designed to make your code easier for other people to understand. - For those internal applications and free software libraries that - we develop at Google, - you should keep within these guidelines when making changes. - Note however that each project has its own rules and customs - that complement or override these general guidelines; - the speed-oriented QPX low fare search engine notably - has a very different style and feel from the QRes reservation system. -
-- If you're writing Common Lisp code outside Google, - we invite you to consider these guidelines. - You may find some of them useful - where they don't conflict with other priorities you have. - We welcome remarks and constructive feedback - on how to improve our guide, and - on what alternate styles work for you and why. -
- -- This guide is not a Common Lisp tutorial. - For basic information about the language, please consult - Practical Common Lisp. - For a language reference, please consult the - Common Lisp HyperSpec. - For more detailed style guidance, take (with a pinch of salt) - a look at Peter Norvig and Kent Pitman's - style guide. -
-- When making decisions about how to write a given piece of - code, aim for the following -ilities in this priority order: -
-- 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. -
- -- 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. -
-- 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. -
-EVAL-WHEN, you should almost always use all of
- (:compile-toplevel :load-toplevel :execute).
- #. sparingly,
- and you must avoid read-time side-effects.
- LIST data structure.
- - You must follow the proper usage regarding - well-known functions, macros and special forms. -
- -&OPTIONAL and
- &KEY arguments.
- You should not use &AUX arguments.
- DYNAMIC-EXTENT
- where it matters for performance,
- and you can document why it is correct.
- NCONC;
- you should use APPEND instead,
- or better data structures.
- -Revision 1.28 -
- - - -Robert Brown - - - - François-René Rideau - - - - - - diff --git a/lispguide.md b/lispguide.md new file mode 100644 index 0000000..a890fba --- /dev/null +++ b/lispguide.md @@ -0,0 +1,1627 @@ +# Google Common Lisp Style Guide + + +## Introduction + +This guide is not a Common Lisp tutorial. Rather, it recommends formatting, +structure, and stylistic choices for Common Lisp code. Maintainers of existing +code should balance these recommendations with the benefit of maintaining +consistency within existing code. + +We welcome constructive feedback on how to improve this guide. If you find +mistakes in this document, you may file bugs in the +[GitHub issue tracker](https://github.com/google/styleguide/issues). Please put +"[Lisp]" in the issue title since the repository contains Style Guides for +several languages. + + +### References + +- For a guide to effective Lisp programming at Google, see + [The Google Lisp Guide to Effective Programming](lispprogrammingguide.md). + +- For basic information about the language, please consult + [Practical Common Lisp](https://www.gigamonkeys.com/book/). + +- For a language reference, please consult the + [Common Lisp HyperSpec](https://www.lispworks.com/documentation/HyperSpec/Front/index.htm). + +- For more detailed style guidance, take (with a pinch of salt) a look at + [Peter Norvig and Kent Pitman's style guide](https://www.cs.umd.edu/~nau/cmsc421/norvig-lisp-style.pdf). + +## Existing Code + +- Fix old code as you go. +- Don't do mass style fixes without warning. + +A lot of Lisp code was written before these guidelines existed. You should fix +violations as you encounter them in the course of your normal coding. Only do so +when such fixes are easy to implement and do not greatly increase the size of +the change. In these cases, consider splitting the style fix into a separate +change. + +You must not fix violations en masse without warning other developers and +coordinating with them, so as not to make the merging of large branches more +difficult than it already is. + +## Formatting + +### Punctuation, Spelling and Grammar + +- Use correct spelling in your comments and code. +- Use proper grammar in your comments and documentation. + +Pay attention to punctuation, spelling and grammar; it is easier to read +well-written comments than badly written ones. + +Comments should be as readable as narrative text, with proper capitalization and +punctuation. In many cases, complete sentences are more readable than sentence +fragments. Shorter comments, such as comments at the end of a line of code, can +sometimes be less formal, but you should be consistent with your style. + +### Line length + +- Format source code so that no line is longer than 100 characters. + +Some line length restriction is better than none at all. While old text +terminals used to make 80 columns the standard, these days, allowing 100 columns +seems better, since good style encourages the use of descriptive variables and +function names. + +### Form length + +- Prefer small and focused top-level forms. + +Long top-level forms (such as functions and macros) are sometimes appropriate, +so no hard limit is placed on their length. If a function or macro exceeds about +40 lines, consider whether it can be broken up without harming the structure of +the program. + +Even if your long form works perfectly now, someone modifying it in a few months +may add new behavior. This could result in bugs that are hard to find. Keeping +your forms short and simple makes it easier for other people to read and modify +your code. + +Do not be intimidated by modifying existing code. If working with an overly long +function proves to be difficult -- errors are hard to debug, or a piece of it is +required in several different contexts -- consider breaking up the function into +smaller and more manageable pieces. + +### Indentation + +- Use spaces, not tabs, to indent code. +- Binding data of a binding form should be: + - indented four spaces when on a new line or + - aligned with the first binding data form otherwise. +- Bodies of a binding form should be: + - indented two spaces when on a new line or + - aligned with the first form in the body otherwise. +- Parameters of a function call should be + - aligned with the call itself when on a new line or + - aligned with the first parameter otherwise. +- Special parameters in function and macro declarations (`&key`, `&optional`, + ...) should be: + - aligned with the special parameter declaration when on a new line or + - aligned with the first special parameter otherwise. +- Prefer fitting all parameters to a function: + - on a single line when possible, or + - one parameter per line otherwise. +- Arguments to a loop form (loop keywords), and their arguments in turn should + be: + - indented two spaces when the first argument is on a new line or + - aligned with the first argument otherwise. + +Common Lisp indentation in Emacs is provided by the cl-indent library. The +latest version of cl-indent is packaged with +[SLIME](https://www.common-lisp.net/project/slime/) (under +contrib/slime-cl-indent.el). After installing SLIME, set up Emacs to load SLIME +automatically using +[these instructions](https://www.common-lisp.net/project/slime/doc/html/Loading-Contribs.html), +adding slime-indentation to the list of contrib libraries to be loaded in the +call to slime-setup. + +Ideally, use the default indentation settings provided by SLIME. If necessary, +customize indentation parameters to maintain a consistent indentation style +throughout an existing project. Parameters can be customized using +the :variables setting in define-common-lisp-style. Indentation of specific +forms can be customized using the :indentation setting of +define-common-lisp-style. This is particularly useful when creating forms that +behave like macros or special operators that are indented differently than +standard function calls (e.g. defun, labels, or let). Add a +[hook](https://www.gnu.org/software/emacs/manual/html_node/emacs/Hooks.html) to +'lisp-mode-hook that calls common-lisp-set-style to set the appropriate style +automatically. + + +You should not include copyright information in individual source code files. An +exception is made for files meant to be disseminated as standalone. + + +### Vertical white space + +- Include one blank line between all top-level forms + - This may be omitted for simple (one-line), closely related forms. + +You should include one blank line between top-level forms, such as function +definitions. Exceptionally, blank lines can be omitted between simple, closely +related defining forms of the same kind, such as a group of related type +declarations or constant definitions. + +```lisp +(defconstant +mix32+ #x12b9b0a1 "pi, an arbitrary number") +(defconstant +mix64+ #x2b992ddfa23249d6 "more digits of pi") + +(defconstant +golden-ratio32+ #x9e3779b9 "the golden ratio") +(defconstant +golden-ratio64+ #xe08c1d668b756f82 "more digits of the golden ratio") + +(defmacro incf32 (x y) + "Like INCF, but for integers modulo 2**32" + `(setf ,x (logand (+ ,x ,y) #xffffffff))) +(defmacro incf64 (x y) + "Like INCF, but for integers modulo 2**64" + `(setf ,x (logand (+ ,x ,y) #xffffffffffffffff))) +``` + +Blank lines can be used to separate parts of a complicated function. Generally, +however, you should break a large function into smaller ones instead of trying +to make it more readable by adding vertical space. If you can't, you should +document with a `;;` comment what each of the separated parts of the function +does. + +### Horizontal white space + +- Don't insert spaces after an opening parenthesis or before a closing + parenthesis. +- Insert a single space between function and macro parameters. +- Don't use whitespace to horizontally align forms. +- Don't have dangling parentheses except when closing a top-level `eval-when` + form. + +You must not include horizontal whitespace after an open parenthesis or before a +close parenthesis. + +You must not place right parentheses by themselves on a line. A set of +consecutive trailing parentheses must appear on the same line. + +```lisp +;; These parentheses pull more attention, hurting readability. This also isn't +;; conventional Lisp style. + ( defun factorial ( limit ) + ( let (( product 1 )) + ( loop for i from 1 upto limit + do (setf product ( * product i ) ) ) + product + ) + ) +``` + +```lisp +;; This is easier to read, and avoids a hanging-braces style that is not +;; conventionally used by Lisp programmers. +(defun factorial (limit) + (let ((product 1)) + (loop for i from 1 upto limit + do (setf product (* product i))) + product)) +``` + +You should use only one space between forms. + +You should not use spaces to vertically align forms in the middle of consecutive +lines. An exception is made when the code possesses an important yet otherwise +not visible symmetry that you want to emphasize. + +```lisp +;; The cost of maintaining this sort of formatting and the inconsistent +;; horizontal spacing outweighs the readability benefit of vertical alignment. +(let* ((low 1) + (high 2) + (sum (+ (* low low) (* high high)))) + ...) +``` + +```lisp +;; Consistent horizontal spacing is preferred. +(let* ((low 1) + (high 2) + (sum (+ (* low low) (* high high)))) + ...)) +``` + +You must align nested forms if they occur across more than one line. + +```lisp +;; Hard to visually grasp how deeply each form is nested. +(defun munge (a b c) +(* (+ a b) +c)) +``` + +```lisp +;; Indentation helps the reader parse the nesting of forms. +(defun munge (a b c) + (* (+ a b) + c)) +``` + +An exception to the rule against lonely parentheses is made for an `eval-when` +form around several definitions; in this case, include a comment `; eval-when` +after the closing parenthesis. + +## Documentation + +### Docstrings + +- Use docstrings whenever the language permits it. +- Use docstrings for all top-level functions, types, classes, variables, and + macros. +- Document how to use a function, including its parameters, return values, and + side effects, not how the code works. +- When a specialization of a generic breaks the contract specified in the + docstring, document that specialization. This must be avoided. + +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. They can be extracted from functions, types, classes, variables and +macros, and displayed by programming tools, such as IDEs, or by REPL queries +such as `(describe 'foo)`; web-based documentation or other reference works can +be created based on them. Documentation strings are thus the perfect locus to +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, use uppercase for the names of Lisp symbols, +such as function arguments. For example, "The value of LENGTH must be an +integer." + +```lisp +(defun small-prime-number-p (n) + "True if N, an integer, is a prime number." + ...) + +(defgeneric clear-table (table) + (:documentation + "Like clrhash, empties TABLE of all associations, and returns TABLE.")) +``` + +A long docstring may usefully begin with a short, single-sentence summary, +followed by the larger body of the docstring. + +When the name of a type is used, the symbol may be quoted by surrounding it with +a back quote at the beginning and a single quote at the end. Emacs will +highlight the type, and the highlighting serves as a cue to the reader that M-. +will lead to the symbol's definition. + +```lisp +(defun bag-tag-expected-itinerary (bag-tag) + "Return a list of `legacy-pnr-pax-segment' objects representing + the expected itinerary of the `bag-tag' object, BAG-TAG." + ...) +``` + +Every method of a generic function should be independently documented when the +specialization affects what the method does, beyond what is described in its +generic function's docstring. + +### Non-Obvious Code + +- When making a non-obvious bug fix, add a comment explaining the reason for + the change and referencing the bug number. +- When writing complicated code, add a comment explaining the need for the + complication and what the code is doing. +- When additional work needs to be done with code, include a TODO. +- Take special care to document any declaration and use of Domain-Specific + Languages (DSLs) in your code. + +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. + +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 truck" principle.) + +Also use comments as a way to guide those who read the code, so they know what +to find where. + +For code that uses obscure forms to accomplish a task, you must include a +comment stating the purpose of the form and the task it accomplishes. + +For comments requiring special attention, such as incomplete code, TODO items, +questions, breakage, and danger, include a TODO comment indicating the type of +problem, its nature, and any notes on how it may be addressed. + +Ideally a TODO comment should reference a bug number: + +```lisp +;; TODO(b/1234567): use circular lists for fizzbuzz +``` + +However, it may also be a username or email address: + +```lisp +;; TODO(zippy@foo.com): Refactor to provide a better API. +``` + +The main purpose is to provide a way to find out more information by looking up +the bug or the person. (Usually you should put your own username.) + +Be specific when indicating times or software releases in a TODO comment and use +[YYYY-MM-DD](https://www.w3.org/TR/NOTE-datetime) format for dates to make +automated processing of such dates easier: + +```lisp +;;--- TODO(brown): Remove this code after release 1.7 or before 2012-11-30. +``` + +You should design your DSL to be easy to read and understand by people familiar +with the domain. + +You must properly document all your DSL. + +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 `CL-PPCRE` package), +you MUST 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. + +### Comment semicolons + +- Use three semicolons for top-level form comments. +- Use two semicolons for comments inside top-level forms. +- Use one semicolon for comments at the end of a line of code. +- Include a space between the semicolons and text of the comment. + +You should use three semicolons to begin comments that apply to the file or the +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. + +```lisp +;;; File-level comments or comments for large sections of code. + +;;; Divisibility +;;; Comments that describe a group of definitions. + +(defun divisorp (d n) + (zerop (mod n d))) + +(defun proper-divisors (n) + ...) + +(defun divisors (n) + (cons n (proper-divisors n))) + +;;; Prime numbers + +(defun small-prime-number-p (n) + (cond ((or (< n 2)) + nil) + ((= n 2) ; parenthetical remark here + t) ; continuation of the remark + ((divisorp 2 n) + nil) ; different remark + ;; Comment that applies to a section of code. + (t + (loop for i from 3 upto (sqrt n) by 2 + never (divisorp i n))))) +``` + +You should include a space between the semicolon and the text of the comment. + +## Naming + +### Symbol guidelines + +- Use all lowercase. +- Use hyphens to separate words. +- Follow the rules for + [punctuation, spelling, and grammar](#punctuation-spelling-and-grammar). +- Name symbols based on their intent, not their content. Exceptions for common + suffixes, such as `-P` and `-V` may be made, but prefer other ways of + conveying type information (including declarations and type-specific + accessor functions) in most situations. +- Function names, variable names, and filenames should be descriptive; eschew + abbreviation. +- Variables with limited scope may be abbreviated freely. + +Use lower case for all symbols. Consistently using lower case makes searching +for symbol names easier and is more readable. + +Note that Common Lisp is case-converting, and that the `symbol-name` of your +symbols will be upper case. Because of this case-converting, attempts to +distinguish symbols by case are defeated, and only result in confusion. While it +is possible to escape characters in symbols to force lower case, you should not +use this capability unless this is somehow necessary to inter-operate with +third-party software. + +Place hyphens between all the words in a symbol. If you can't easily say an +identifier out loud, it is probably badly named. + +You must not use `"/"` or `"."` instead of `"-"` unless you have a +well-documented overarching reason to, and permission from other hackers who +review your proposal. + +```lisp +;; Bad +(defvar *default-contextname* "main") ; Words run together +(defvar *maximum-widget-cnt* 200) ; Abbreviation to save two characters +``` + +```lisp +;; Better +(defvar *default-context-name* "main") ; Words separated by dashes +(defvar *maximum-widget-count* 200) ; Uses full words +``` + +There are [conventions](https://www.cliki.net/Naming+conventions) in Common Lisp +for the use of punctuation in symbols. You should not use punctuation in symbols +outside these conventions. + +Give as descriptive a name as possible, within reason. Do not worry about saving +horizontal space as it is far more important to make your code immediately +understandable by a new reader. + +Do not use abbreviations that are ambiguous for symbols with a wide scope; such +as `defvar`s or `defun`s. For abbreviations that are unfamiliar to readers +outside your project, domain-specific abbreviations, centrally document these +abbreviations. For symbols of limited scope, such as those bound within a +function, abbreviate freely. + +```lisp +(defvar *n*) ; Meaningless. +(defvar *nerr*) ; Ambiguous abbreviation. +(defvar *n-comp-conns*) ; Ambiguous abbreviation. +(defvar *wgc-connections*) ; Only your group knows what this stands for. +(defvar *pc-reader*) ; Lots of things can be abbreviated "pc". +(defvar *cstmr-id*) ; Deletes internal letters. +``` + +```lisp +(defvar *price-count-reader*) ; No abbreviation. +(defvar *num-errors*); ; "num" is a widespread convention. +(defvar *num-dns-connections*) ; Most people know what "DNS" stands for. +``` + +You should name a variable according to the high-level concept that it +represents, not according to the low-level implementation details of how the +concept is represented. + +Thus, you should avoid embedding data structure or aggregate type names, such as +`list`, `array`, or `hash-table` inside variable names, unless you're writing a +generic algorithm that applies to arbitrary lists, arrays, hash-tables, etc. In +that case it's perfectly OK to name a variable `list` or `array`. + +Indeed, you should be introducing new abstract data types with `defclass` or +`deftype`, whenever a new kind of intent appears for objects in your protocols. +Functions that manipulate such objects generically may then use variables the +name of which reflect that abstract type. + +For example, if a variable's value is always a row (or is either a row or +`nil`), it's good to call it `row` or `first-row` or something like that. It is +alright if `row` has been `deftype`'d to `string` — precisely because you have +abstracted the detail away, and the remaining salient point is that it is a row. +You should not name the variable `string` in this context, except possibly in +low-level functions that specifically manipulate the innards of rows to provide +the suitable abstraction. + +Be consistent. If a variable is named `row` in one function, and its value is +being passed to a second function, then call it `row` rather than, say, `value` +(this was a real case). + +### Global variables and constants + +- Global constants should start and end with a plus character. +- Global variables should start and end with an asterisk character. + +The names of global constants should start and end with plus characters. + +Global variable names should start and end with asterisks (also known in this +context as earmuffs). + +In some projects, parameters that are not meant to be usually modified or bound +under normal circumstances (but may be during experimentation or exceptional +situations) should start (but do not end) with a dollar sign. If such a +convention exists within your project, you should follow it consistently. +Otherwise, you should avoid naming variables like this. + +Common Lisp does not have global lexical variables, so a naming convention is +used to ensure that globals, which are dynamically bound, never have names that +overlap with local variables. It is possible to fake global lexical variables +with a differently named global variable and a `define-symbol-macro`. You should +not use this trick, unless you first publish a library that abstracts it away. + +```lisp +(defconstant +hash-results+ #xbd49d10d10cbee50) +(defvar *maximum-search-depth* 100) +``` + +### Predicate names + +- For single-word predicate names, use a trailing `"p"`. +- For multi-word predicate names, use a trailing `"-p"`. + +You should name functions returning a generalized-Boolean value with a trailing +`"p"` or `"-p"`, to indicate that they are Boolean predicates. The value of +`nil` means "false", while any other value means "true". The returned value +should not have any other meaning beyond expressing the truth of the predicate. +Generally, you should use `"p"` when the rest of the function name is one word +and `"-p"` when it is more than one word. + +A rationale for this convention is given in +[the CLtL2 chapter on predicates](https://www.cs.cmu.edu/Groups/AI/html/cltl/clm/node69.html). + +Functions that return meaningful values beyond the truth value, for example +`cl:member`, should not be named with a `-p` or `p` suffix even if their return +value can be used as a +[generalized boolean](https://www.lispworks.com/documentation/HyperSpec/Body/26_glo_g.htm#generalized_boolean). + +The suggested convention for naming Boolean variables is to suffix their names +equally with "-p" or "p" if there is no other convenient name that would express +their Boolean type. + +### Omit library prefixes + +- Don't include a library or package name as a prefix within the name of + symbols. + +When naming a symbol (external or internal) in a package, you should not include +the package name as a prefix within the name of the symbol. Naming a symbol this +way makes it awkward to use from a client package accessing the symbol by +qualifying it with a package prefix, where the package name then appears twice +(once as a package prefix, another time as a prefix within the symbol name). + +```lisp +(in-package #:varint) +(defun varint-length64 () ... ) + +(in-package #:client-code) +(defconst +padding+ (varint:varint-length64 +end-token+)) ; varint is repeated +``` + +```lisp +(in-package #:varint) +(defun length64 () ... ) + +(in-package #:client-code) +(defconst +padding+ (varint:length64 +end-token+)) ; reads nicely with package +``` + +An exception to the above rule is to include a prefix for the names of variables +that would otherwise be expected to clash with variables in packages that use +the current one. For instance, `ASDF` exports a variable `*asdf-verbose*` that +controls the verbosity of `ASDF` only, rather than of the entire Lisp program. + +Symbols that correspond to standard, idiomatic Lisp expressions and would +contain the package name or a part of it in a non-prefix position are still to +be written with that package name or part. This includes the following idiomatic +Lisp expressions as example: + +```lisp +;; Definition of the FOOBAR concept. +(foobar:define-foobar ...) +;; Iterate over elements of FOOBAR. +(foobar:do-foobar ...) +;; Establish a lexical scope dealing with some aspect of FOOBAR. +(foobar:with-frobed-foobar ...) +;; Constructors. +(foobar:make-foobar ...) +(foobar:new-foobar ...) +``` + + +### Package names + +- Design package names to be usable as prefixes for symbols. +- Usually, the last package name part will end up as an alias in other code. + +Follow consistent conventions when choosing a package name. For packages that +are intended for wide use and may be exposed outside of your organization a good +rule of thumb is to use `