Lisper 是做什麼的?
操作規則
將此技能視為一系列斷言。將每個斷言視為已滿足、已違反,或因使用者限制而明確推遲。偏好確切的程式碼事實而非個人品味。命名使斷言成立的套件、符號、結構體、條件、巨集展開、不變量、測試或副作用邊界。
陳述事實。命名見證者。不要爭論品味。
在報告 Common Lisp 或 Emacs Lisp 程式碼時,使用簡短的陳述句書寫:
- 不變量存在於建構子中。
- 動態範圍由
unwind-protect界定。 - 該巨集洩漏了求值順序。
- 該條件是結構化的。
- 破壞性列表操作改變了呼叫者的結構。
- 該謂詞是裸的(未封裝)。
- 編譯器警告仍然存在。
- 緩衝區效果洩漏到純核心中。
斷言
-
程式碼描繪模型。S-表達式在成為文字之前就是語法樹。保留問題的每個真實狀態。使用符號、標記結構(
defstruct/cl-defstruct)、CLOS 類別,或帶有顯式建構子的代數關聯列表/屬性列表。僅擦除那些在語義上未使用的區別。 -
高階函數在巨集重寫之前進行組合。Lisp 首先是 lambda 演算:函數是一等值,閉包攜帶詞法環境,柯里化(
apply-partially或返回(lambda (x) ...))取代多參數管道。當同一結構出現兩次時,檢查它;當出現三次時,用高階組合子、柯里化閉包或泛型函數來抽象化——絕對不要用一個 10 參數的程序化輔助函數。僅在控制求值、綁定詞法符號或消除編譯時代碼模板時引入巨集。每個巨集必須最多從左到右求值一次值參數,並使用gensym/make-symbol(with-gensyms)綁定臨時變量。 -
純資料轉換保持在鏡像(image)的可變世界之外。偏好 catamorphisms(
cl-reduce/seq-reduce)、同態映射(mapcar/seq-keep)與謂詞管道(seq-filter),而非命令式的let+setq+push+nreverse迴圈。將純符號/列表/結構轉換與緩衝區變異、進程 I/O、檔案系統狀態、網路串流、計時器和全域特殊變數(*earmuffs*)分離。核心函數接收值並返回值。宿主效果保留在命名的邊界函數中。 -
詞法作用域是預設法則。每個 Emacs Lisp 檔案必須以
;; -*- lexical-binding: t; -*-開頭。Common Lisp 或 Emacs Lisp 中的每個動態特殊變數必須帶有*earmuffs*(或在 CL 中常數用+plus-signs+),並使用let進行動態綁定,而不是使用setq/setf全域變異,除非改變全域設定是明確的合約。 -
不變量是命題。首先在型別中表達不變量(使用
satisfies的deftype、ftype宣告、defstruct:type插槽),其次是智慧建構子(:constructor),再次是執行時斷言(check-type/cl-check-type),接著是測試,最後是註解。建構子是證明結構滿足其插槽不變量的證據。 -
條件是代數事實,而非原始字串。定義明確的條件層次結構(Common Lisp 中的
define-condition;Emacs Lisp 中的define-error)。使用error/cerror/signal發送結構化條件,以便呼叫者可以使用handler-case、handler-bind或condition-case處理它們,而無需匹配錯誤訊息子字串。當恢復策略屬於呼叫者且機制屬於底層函數時,使用 Common Lisp 重啟(restart-case)。 -
Cons-cell 所有權是一個語義聲明。除非函數的名稱和文檔字串明確聲明破壞性行為(
nreverse、nconc、delete、sort、cl-delete、對共享 cons cell 的setf),否則將輸入列表、樹和序列視為不可變。絕不要對引號文字'(a b c)或借用的呼叫者列表應用破壞性操作。僅在變異開始的邊界處複製結構(copy-list、copy-tree、copy-sequence)。 -
品質是被見證的,而非斷言的。零字節碼編譯器警告、零
checkdoc/package-lint錯誤、以及零 SBCLSTYLE-WARNING診斷只是地板。為純轉換、巨集展開法則、邊界輸入、非局部退出下的動態清理以及修復的回歸問題添加 ERT(ert-deftest)或 FiveAM/Rove/Parachute 測試。測試名稱陳述了它所見證的命題。 -
文件化和命名空間前綴是公開合約的一部分。
- 在 Common Lisp 中:定義明確的套件(
defpackage/uiop:define-package),避免超出:cl的全域:use污染;為每個匯出的函數、巨集、類別、變數和條件撰寫文件。 - 在 Emacs Lisp 中:為每個公開符號加上
<package>-前綴,為每個內部符號加上<package>--前綴;撰寫符合checkdoc規範的文檔字串,其第一行是完整的句子,並且參數引用是UPPERCASE;正確宣告Package-Requires和;;; Commentary:標頭。
- 在 Common Lisp 中:定義明確的套件(
-
資源生命週期由動態範圍界定。絕不要跨可能失敗的表達式配對手動分配和清理。將每個臨時緩衝區更改、點移動、檔案控制代碼、進程、套接字或鉤子安裝包裝在
unwind-protect(或with-open-file、with-temp-buffer、save-excursion、save-restriction、save-match-data)中。非局部退出(throw、return-from、signal、error)必須保持全域狀態和緩衝區清潔。 -
大小和括號佈局是結構訊號。保持每個源檔案在 1000 行以下,每個
defun/defmacro可執行主體(排除其文檔字串和declare形式)在 80 行以下。絕不要為了玩弄行數限制而截斷文檔字串、刪除解釋性註解,或將多個順序副作用形式打包到單行中。絕不要將閉合括號)))單獨放在行尾。根據標準 Lisp 形式語義縮排(在每個 Elisp 巨集上宣告(declare (indent ...)))。根據領域命題分割檔案和函數,而不是根據隨意的行數切片或模糊的utils桶。 -
邏輯需要命名。當表達領域命題時,不要在調用點暴露原始的
car/cdr/nth鏈(cadddr)、巢狀的assoc/plist-get管線,或多子句的and/or/not表達式。定義命名存取器和以-p或p結尾的語義謂詞(例如order-matchable-p、same-principal-p、session-active-p)。
模型完整性
在選擇套件、結構體和函數之前,命名使程式碼一致的正式模型。
對於巨集和語法轉換:
- 巨集是從語法到語法的編譯器傳遞:$\text{AST}{\text{surface}} \to \text{AST}{\text{core}}$。
- 指定表層語法(解構 lambda 列表)、綁定紀律、每個子形式的求值次數以及目標展開。
- 使用
macroexpand-1/macrostep驗證衛生性:無自由符號捕獲、無對具有副作用的參數進行多次求值、無執行時eval。 - 如果巨集展開為定義,為宿主編譯器和檢查器保留原始碼位置和宣告(
declare、文檔字串位置)。
對於互動狀態、緩衝區和並發進程:
- 互動系統在成為緩衝區或執行緒之前是一個狀態轉換關係。
- 將領域狀態值與渲染緩衝區(Emacs UI)或工作者執行緒/套接字(CL/Emacs 進程)分離。
- 將非同步進程輸出(Emacs 進程過濾器/哨兵、CL 執行緒/通道)建模為離散事件,饋入總體狀態轉換:$\text{State} \times \text{Event} \to (\text{State} \times \text{List}[\text{Effect}])$。
- Emacs Lisp 中的進程過濾器可能接收任意分塊邊界;在分派領域事件之前,明確地緩衝和解析不完整的幀。
- 當計時器、哨兵或回調非同步觸發時,保護緩衝區局部狀態(
defvar-local)免受已殺死緩衝區(buffer-live-p)的影響。
對於條件、重啟和非局部控制:
- 將出了什麼問題(條件資料)與如何恢復(CL 中的重啟;Elisp 中的結構化處理程式)以及選擇哪種恢復(外部策略處理程式)分開。
- 絕不要使用裸
(ignore-errors ...)或(condition-case nil ... (error nil))吞沒條件,除非已縮小確切忽略的條件類型,且回退值是有效的領域狀態。
形式邏輯註解
僅當形式註解能闡明 ftype、deftype 或 cl-defstruct 未能完全表達的證明義務時使用它們。在函數/形式內部使用 ;;,在頂層使用 ;;;,遵循標準 Lisp 註解層次結構(;;;; 節、;;; 頂層、;; 對齊於主體內、; 邊緣)。
;;; Pre: (and ( <= 0 start end (length sequence)) (listp sequence))
;;; Post: (and (equal result (subseq sequence start end))
;;; (not (eq result sequence)))
(defun slice-copy-checked (sequence start end)
"Return a fresh subsequence of SEQUENCE from START to END."
(check-type sequence list)
(assert (<= 0 start end (length sequence)))
(copy-list (subseq sequence start end)))
;;; Invariant: (null (intersection (work-set-pending ws) (work-set-completed ws) :test #'equal))
;;; Preservation: `work-set-complete' removes ID from `pending' before consing onto `completed'.
(defstruct (work-set (:copier nil))
(pending nil :type list)
(completed nil :type list))
;;; Law: (equal (decode-packet (encode-packet x)) x) for all valid packet structs X.
偏好這些形式:
Pre:呼叫者必須滿足的條件。Post:函數保證的條件,包括新鮮度/共享(eqvsequal)。Invariant:在結構/緩衝區/會話操作中保持成立的命題。Law:測試必須見證的代數或巨集展開關係。Preservation:為何某個轉換或unwind-protect形式保持不變量為真。
語義謂詞
使用遵循 Lisp -p / p 慣例的命名謂詞來聲明性地表達領域邏輯:
- 單詞根(Common Lisp 慣例):
evenp、Orderp->orderp、validp(或在 Elisp 中,對套件前綴符號一致使用-p)。 - 連字符根(CL 和 Elisp 均可):
order-matchable-p、same-principal-p、lispm-session-live-p。
偏好:
(when (order-matchable-p order resting-order)
(match-order book order resting-order))
(when (same-principal-p actor owner)
(grant-access actor resource))
避免:
(when (and (not (eq (order-side order) (order-side resting-order)))
(>= (order-price order) (order-price resting-order))
(plusp (order-quantity order)))
(match-order book order resting-order))
(when (and (equal (principal-id actor) (principal-id owner))
(eq (principal-realm actor) (principal-realm owner)))
(grant-access actor resource))
同時避免在領域邏輯中使用深層位置列表存取((cadddr record)、(nth 4 item));定義一個 defstruct / cl-defstruct 或命名存取器函數,以使調用點讀取領域概念而非 cons 拓撲。
實作紀律
從領域出發,並尊重方言的函數式語義。
- 柯里化、部分應用和組合子:
- 絕不要通過提取一個帶有 6+ 個位置參數(這些參數反映了呼叫者的
let*綁定)的程序化輔助函數,或通過將let*切片成一次性使用的foo--part-1/foo--part-2子程序,來分解長函數。 - 絕不要引入「假柯里化」(例如
(lambda (getter-fn) (lambda () ...)))來模擬一個局部let*已提供的詞法作用域。 - 相反地,將真正的領域不變量柯里化到詞法閉包中(
(defun domain--matcher (query role) (lambda (event) ...))或(apply-partially #'fn fixed-arg)),並組合小的單元/二元轉換:$f \circ g = \lambda x. f(g(x))$。 - 用接受步驟函數
(funcall step item)並返回值的高階組合子取代重複的命令式輪詢、循環安全圖遍歷或資源括號模式。
- 絕不要通過提取一個帶有 6+ 個位置參數(這些參數反映了呼叫者的
- 相等性精度:絕不要使用
eq當需要eql(數字/字元)、equal(結構性字串/列表)或equalp/ 領域相等性時。選擇與型別等價關係最匹配的最嚴格相等謂詞,並在鍵是字串或複合值時,向assoc、member、gethash、remove和cl-find顯式傳遞:test #'equal。 - Emacs Lisp 特例:
- 第 1 行必須宣告
;; -*- lexical-binding: t; -*-。 - 使用
cl-lib(cl-defstruct、cl-loop、cl-destructuring-bind、cl-check-type),絕不使用已棄用的執行時cl套件。 - 使用
save-excursion、save-restriction和save-match-data保護所有點、標記、縮小和匹配資料副作用。 - 偏好傳遞緩衝區或顯式
(with-current-buffer buf ...),而非跨非同步邊界假設current-buffer。 - 用
(declare (indent ...) (debug ...))註解巨集,以使縮排和 Edebug 檢測自動工作。
- 第 1 行必須宣告
- Common Lisp 特例:
- 為公開領域函數宣告
(declaim (ftype (function (...) ...) name)),以便 SBCL 執行編譯時型別推斷和窮盡性檢查。 - 使用
etypecase/ecase/ctypecase而非開放式的case/typecase,以便未處理的變體立即發出結構化型別錯誤訊號。 - 避免讀取器表格污染和未匯出符號洩漏(
pkg::internal-sym)。 - 偏好 ASDF「package-inferred」或帶有清晰依賴 DAG 的顯式序列
:components。
- 為公開領域函數宣告
- 生產路徑中的禁止結構:
- 無執行時
eval用於分派函數或建構程式碼(改用funcall、apply或編譯時巨集)。 - 無對未宣告自由變數的動態
setq。 - 無對引號文字或非擁有的呼叫者列表進行原地變異(
nconc、nreverse、delete、sort)。
- 無執行時
…
[為翻譯而截斷]