From 403f0581bd93732111cc8f84f92b07ce1ed50d82 Mon Sep 17 00:00:00 2001 From: Mike Frysinger Date: Tue, 29 Sep 2026 11:06:26 -0400 Subject: [PATCH] lisp: export latest after fixing external replacement --- lispguide.md | 53 +++++++++++++++++++++++++++++++++++------ lispprogrammingguide.md | 7 ------ 2 files changed, 46 insertions(+), 14 deletions(-) diff --git a/lispguide.md b/lispguide.md index a890fba..1f219d4 100644 --- a/lispguide.md +++ b/lispguide.md @@ -1,6 +1,5 @@ # Google Common Lisp Style Guide - ## Introduction This guide is not a Common Lisp tutorial. Rather, it recommends formatting, @@ -14,7 +13,6 @@ mistakes in this document, you may file bugs in the "[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 @@ -132,11 +130,9 @@ standard function calls (e.g. defun, labels, or let). Add a '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 @@ -654,7 +650,6 @@ organization. If a component of the package name is a compound noun use a hyphen (-) to separate the words. For example, `ace.container.hash-table`. As with other Lisp names, use lowercase, even for well-known abbreviations like "http". - Package prefixes should fit the names of the symbols those packages export. For example, if you have an abstraction called `fifo`, and it is in a package of the first type you'd have functions named things like `fifo-add-to` and @@ -765,7 +760,6 @@ different nicknames throughout their code, thus reducing readability and the ability to process the code with automatic tools that are agnostic to Lisp package naming schemes. - - Favor the one package per file design principle, instead of sharing a package across multiple files in a library. @@ -781,7 +775,6 @@ package naming schemes. if they depend on each other in a circular fashion. This improves the software architecture and design. - - Do not shadow `common-lisp` symbols. Your package must not shadow (and thus effectively redefine) symbols that are @@ -912,6 +905,52 @@ assignments. ### Assertions and Conditions +Use `assert`, `check-type`, and `etypecase` to detect internal bugs only, and use them liberally. +- Prefer `etypecase` over `typecase` +- Use `error` to check input from a file. +- If a function signals an error, document it in its contract. +- Prefer `log`ging a warning to using `warn`. +- Never call `signal` directly, use `error` instead. +- Prefer using `handler-bind` to `restart`. +- Prefer using `restart` to `throw` and `catch`. +- Avoid generically handling conditions: + - Errors not related to the current code should propagate through. + - Avoid generically handling `serious-condition`. +- Never signal conditions within the clean-up of an `unwind-protect`. +- Never clean up by resignaling. +- Never return a condition or error value, signal it with ERROR instead. + +Use `assert` to detect internal bugs ONLY. +Code should `assert` invariants whose failure indicates that the software is +itself broken. Incorrect input should be handled properly at runtime, and must +not cause an assertion violation. The audience for an `assert` failure is a +developer. Do not use the data-form and argument-form in `assert` to specify a +condition to signal. It's fine to use them to print out a message for debugging +purposes (and since it's only for debugging, there's no issue of +internationalization). + +`check-type`, `etypecase` are also forms of assertion. When one of these fails, +that's a detected bug. Prefer `check-type` over `(declare (type ...))` for the +inputs of functions. + +Invalid input, such as files that are read but do not conform to the expected +format, should not be treated as assertion violations. Always check to make sure +that input is valid, and take appropriate action if it is not, such as signaling +an application specific error. + +Use `error` to signal problems with user data, requests, permissions, etc., or +to report "unusual outcomes" to the caller. + +Always call `error` with an explicit condition type; it should never simply be +called with a string in production code. This enables internationalization. + +Functions that report unusual outcomes by signaling a condition should say so +explicitly in their contracts (their textual descriptions, in documentation and +docstrings etc.). When a function signals a condition that is not specified by +its contract, that's a bug. The contract should specify the condition class(es) +clearly. The function may then signal any condition that is a type-of any of +those conditions. That is, signaling instances of subclasses of the documented +condition classes is fine. Code must not call `signal`. Use `error` instead. diff --git a/lispprogrammingguide.md b/lispprogrammingguide.md index 69e9ab8..4f7da45 100644 --- a/lispprogrammingguide.md +++ b/lispprogrammingguide.md @@ -1,6 +1,5 @@ # Google Common Lisp Effective Programming - ## Introduction This document is intended as a supplement to the @@ -36,7 +35,6 @@ new Lisp programmers. software you're writing, and must not be considered available for use. Be aware of these issues, or consult with people who are. - ### Avoid Allocation - Make sure objects are no longer reachable after they're no longer needed. @@ -109,7 +107,6 @@ and slower optimize settings; this is good to locate a dynamic error in your code during development, but is not to be used for production code since it defeats the purpose of declarations as a performance trick. - ### DYNAMIC-EXTENT - Treat `DYNAMIC-EXTENT` as an unsafe operation, profile any code using it and @@ -221,7 +218,6 @@ from a suitable library (that you may have to contribute to) that properly handles those cases without burdening users with implementation details. See for instance `UIOP:REDUCE/STRCAT`. - ### NCONC and MAPCAN - Don't use `NCONC` or `MAPCAN`. @@ -336,7 +332,6 @@ complexities and rounding errors of floating-point arithmetic. Libraries such as this library is not satisfactory, see above about [Using Libraries](#using-libraries). - ### Case and Ecase - Use `CASE` and `ECASE` for numbers, characters, and symbols only. @@ -522,7 +517,6 @@ ways. You should use other pathname abstractions, such as `ASDF:SYSTEM-RELATIVE-PATHNAME` or the underlying `UIOP:SUBPATHNAME` and `UIOP:PARSE-UNIX-NAMESTRING`. - Finally, be aware that paths may change between the time you build the Lisp image for your application, and the time you run the application from its image. You should be careful to reset your image to forget irrelevant build-time paths @@ -531,7 +525,6 @@ instance requires you to reset its paths with `UIOP:CLEAR-CONFIGURATION`. `UIOP` provides hooks to call functions before an image is dumped, from which to reset or `makunbound` relevant variables. - ### SATISFIES - You must be careful when using a `SATISFIES` clause in a type specifier.