D.7 注释编写技巧

我们推荐遵循以下注释规范:

;

以单个分号 ‘;’ 开头的注释,应在源码右侧对齐到同一列。 这类注释通常用于说明当前行代码的工作方式。例如:

(setq base-version-list                 ; 存在一个基础版本
      (assoc (substring fn 0 start-vn)  ; 用于匹配该版本
             file-version-assoc-list))  ; 看起来像是其子版本
;;

以两个分号 ‘;;’ 开头的注释,应与代码缩进级别对齐。 这类注释通常用于说明后续代码的用途,或程序在当前位置的状态。例如:

(prog1 (setq auto-fill-function
             ...
             ...
  ;; Update mode line.
  (force-mode-line-update)))

我们通常也在函数外部使用两个分号的注释。

;; This Lisp code is run in Emacs when it is to operate as
;; a server for other processes.

如果一个函数没有文档字符串,应在函数前使用双分号注释, 说明函数功能与正确调用方式。 精确解释每个参数的含义,以及函数如何处理其可能取值。 不过,将这类注释改为文档字符串会更好。

;;;

以三个(或更多)分号 ‘;;;’ 开头的注释,应从最左列开始。 我们用这类注释作为大纲次要模式可识别的标题。 默认情况下,以至少三个分号(后接一个空格和非空白字符)开头的注释会被视为章节标题, 两个及以下分号则不会。

(历史上,三分号注释也曾用于在函数内注释掉整行代码, 但现在不鼓励这种用法,建议只用两个分号。 注释掉整个函数时同样如此。)

三个分号用于顶层章节,四个分号用于子节,五个分号用于子子节,依此类推。

通常一个库至少包含四个顶层章节。例如所有章节内容折叠时:

;;; backquote.el --- implement the ` Lisp construct...
;;; Commentary:...
;;; Code:...
;;; backquote.el ends here

(从某种意义上说,最后一行并非章节标题,因为其后绝不能有任何内容,它用于标记文件结束。)

对于较长的库,建议将代码分为多个章节。 可以把 ‘Code:’ 一节拆成多个子节实现。 尽管这在很长一段时间内是唯一推荐的方式,但很多人还是选择使用多个顶层代码节。 你可以任选一种风格。

使用多个顶层代码节的好处是避免增加额外嵌套层级, 但缺点是名为 ‘Code’ 的节并不包含全部代码,略显怪异。 为避免这一问题,你可以在该节内不放置任何代码,使其仅作为分隔符而非标题。

最后,我们建议标题不要以冒号或其他标点结尾。 由于历史原因,‘Code:’ 和 ‘Commentary:’ 以冒号结尾, 但其他标题建议不要这样做。

一般来说,M-;comment-dwim)命令会根据分号数量, 自动新建合适类型的注释,或将已有注释缩进至正确位置。 See Manipulating Comments in The GNU Emacs Manual.