Next: 按键绑定规范, Up: 技巧与规范   [Contents][Index]

---

D.1 Emacs Lisp 编码规范 ¶

以下是编写面向广泛使用的 Emacs Lisp 代码时应当遵守的规范：

• 仅加载一个包不应改变 Emacs 的编辑行为。 应提供一个或多个命令用于启用、禁用该功能，或直接调用该功能。

  对于包含自定义定义的任何文件，该规范都是强制性要求。 若修复此类文件以遵守该规范需要引入不兼容变更，应直接执行该不兼容变更，不要推迟。

• 应选择一个简短的单词，将你的程序与其他 Lisp 程序区分开。 程序中所有全局符号的名称，即变量、常量和函数的名称，都应以该选定前缀开头。 使用连字符 ‘-’ 分隔前缀与名称其余部分。 该做法有助于避免命名冲突，因为 Emacs Lisp 中所有全局变量共用同一个命名空间， 所有函数共用另一个命名空间³⁵。 若该符号不打算被其他包使用，可用两个连字符分隔前缀与名称。

  偶尔，对于面向用户使用的命令名称，若部分单词放在包名前缀之前会更易用，也可如此处理。 例如，我们约定列出对象的命令命名为 ‘list-something’， 比如名为 ‘frob’ 的包可以有命令 ‘list-frobs’，而其其他全局符号仍以 ‘frob-’ 开头。 此外，定义函数、变量等的构造体以 ‘define-’ 开头通常效果更好，因此可以将名称前缀放在稍后位置。 但除了这些既定场景外，应优先在名称前添加前缀。

  若你编写了一个函数，认为其应当以某个名称加入 Emacs（如 twiddle-files）， 不要在你的程序中直接使用该名称。应在程序中将其命名为 mylib-twiddle-files， 并发送邮件至 ‘[email protected]’ 建议我们将其加入 Emacs。 当我们采纳时，再修改名称即可。

  若一个前缀不够用，你的包可以使用两到三个通用前缀，只要命名合理即可。

• 我们建议在新代码中启用 lexical-binding， 并将未启用该特性的现有 Emacs Lisp 代码改造为启用状态。See 选择 Lisp 方言。
• 在每个独立的 Lisp 文件末尾添加 provide 调用。See 功能。
• 若某个文件需要预先加载其他特定 Lisp 程序， 文件开头的注释应予以说明。同时使用 require 确保其被加载。See 功能。
• 若文件 foo 使用了另一个文件 bar 中定义的宏， 但未使用 bar 中的任何函数或变量，则 foo 应包含如下表达式：

  (eval-when-compile (require 'bar))
  

  该语句告知 Emacs 在字节编译 foo 之前加载 bar， 从而保证编译期间宏定义可用。 使用 eval-when-compile 可以避免在使用 foo 的编译版本时加载 bar。 该语句应放在文件中首次使用该宏之前。See 宏与字节编译。

• 避免在运行时加载额外库，除非确实需要。 若你的文件离开某个库无法正常工作，直接在顶层 require 该库即可。 但若文件包含多个独立功能，仅其中一两个需要额外库， 则考虑将 require 语句放在相关函数内部而非顶层， 或使用 autoload 语句在需要时加载额外库。 这样，不使用这些功能的用户就无需加载该额外库。
• 若需要使用 Common Lisp 扩展，应使用 cl-lib 库， 而非旧的 cl 库。后者已被废弃，并将在未来版本的 Emacs 中移除。
• 定义主模式时，请遵守主模式相关规范。See 主模式编码规范。
• 定义次要模式时，请遵守次要模式相关规范。See 编写次要模式的规范。
• 若函数的用途是判断某个条件是否成立， 应给函数命名时添加后缀 ‘p’（代表“谓词 predicate”）。 若名称为单个单词，直接添加 ‘p’；若为多个单词，添加 ‘-p’。 例如 framep 和 frame-live-p。 我们建议布尔变量名避免使用 -p 后缀，除非该变量绑定到谓词函数； 可改用 -flag 后缀或 is-foo 这类名称。
• 若变量用于存放单个函数，名称应以 ‘-function’ 结尾。 若变量用于存放函数列表（即钩子变量），请遵守钩子命名规范。See 钩子。
• 使用 unload-feature 会撤销加载特性时通常执行的修改（如向钩子添加函数）。 但是，若加载 feature 时执行了特殊且复杂的操作， 可以定义名为 feature-unload-function 的函数，用于撤销这些特殊修改。 unload-feature 会在该函数存在时自动运行。See 卸载。
• 为 Emacs 原语定义别名是不可取的。 通常应直接使用标准名称。别名仅在用于兼容旧版本或提升可移植性时才有意义。
• 若某个包需要为兼容其他版本 Emacs 定义别名或新函数， 命名时应带上包前缀，而非直接使用其在另一版本中的原始名称。 以下是 Gnus 中的示例，该包包含大量此类兼容处理场景。

  (defalias 'gnus-point-at-bol
    (if (fboundp 'point-at-bol)
        'point-at-bol
      'line-beginning-position))
  

• 重定义或 advising Emacs 原语是不可取的。 这可能对特定程序有效，但无法保证不会破坏其他程序。
• 同理，一个 Lisp 包也不应 advising 另一个 Lisp 包中的函数。see 为 Emacs Lisp 函数添加建议。
• 在库和包中避免使用 eval-after-load 和 with-eval-after-load。see 加载相关钩子。 该特性专为个人定制设计；在 Lisp 程序中使用会导致结构不清晰， 因为它会以文件中不可见的方式修改另一个 Lisp 文件的行为。 这会给调试带来障碍，与 advising 其他包中的函数类似。
• 若某个文件替换了 Emacs 的标准函数或库程序， 文件开头应添加醒目注释，说明替换了哪些函数，以及替换后的行为与原版有何不同。
• 用于定义函数或变量的构造体应是宏而非普通函数， 且名称应以 ‘define-’ 开头。 宏应将待定义的名称作为第一个参数， 这有助于各类工具自动找到其定义。 避免在宏内部构造名称，否则会导致这些工具无法识别。
• 部分其他系统有变量名以 ‘*’ 开头和结尾的规范。 Emacs Lisp 不使用该规范，因此请勿在程序中使用。 （Emacs 仅将此类名称用于特殊用途的缓冲区。） 所有库遵循统一规范会让 Emacs 整体更一致。
• Emacs Lisp 源文件默认的文件编码为 UTF-8。see 文本表示方式。 极少数情况下，若程序包含 不属于 UTF-8 的字符， 应在源文件的 ‘-*-’ 行或局部变量列表中指定合适的编码系统。 See Local Variables in Files in The GNU Emacs Manual.
• 使用默认缩进参数对文件进行缩进。
• 不要养成将右括号单独放在一行的习惯；Lisp 程序员会对此感到不适。
• 若你分发文件，请在文件中添加版权声明和复制许可声明。See Emacs 库的标准文件头。
• 对于存放（或返回）文件或目录名的变量及函数， 命名时避免使用 path，优先使用 file、file-name 或 directory。 因为 Emacs 遵循 GNU 规范，仅将术语 路径(path) 用于搜索路径（即目录名列表）。