我们推荐遵循以下注释规范:
以单个分号 ‘;’ 开头的注释,应在源码右侧对齐到同一列。 这类注释通常用于说明当前行代码的工作方式。例如:
(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.