Lisp评论大会

Question

有关用于不同类型注释的分号数量(以及不同数量的分号的缩进程度应该是多少)的Lisp约定是什么？

另外,是否有关于何时使用分号注释以及何时使用的约定#|multiline comments|#(假设它们存在且存在于多个实现中)？

Answer 1

在Common Lisp中:

;;;; At the top of source files

;;; Comments at the beginning of the line

(defun test (a &optional b)
  ;; Commends indented along with code
  (do-something a)                      ; Comments indented at column 40, or the last
  (do-something-else b))                ; column + 1 space if line exceeds 38 columns

注意:Emacs并不能#| |#很好地说明,但正如Rainer在评论中所建议的那样,请尝试使用#|| ||#.

我会说没有规则可以使用这个,但我认为它可以更快地评论大量的代码,或者插入一些长的描述,其中分号只是在编辑的方式,如巨大的BNF列表等.

有一个巧妙的技巧来禁用代码,用于为表达式添加前缀#+(or):

(defun test (a &optional b)
  #+(or)
  (do-something a)
  (do-something-else b))

注意:#+nil通常也可以,除非你碰巧有一个nil或一个:nil功能.优点#+(or)是您可以通过注释或更改它来轻松编辑它#+(and),或者实际包含一组您真正想要读取该表达式的功能.

(do-something a)当你运行Lisp时,SLIME通过将表单作为注释来表示帮助.

除了Common Lisp的特殊注释语法和技巧,例如#| |#和/ #+(or)或更常见的#+nil,我相信分号规则也被广泛采用在其他lisps中.

以下是规范的摘录,请注意当前实践在单个分号上的分歧:

2.4.4.2关于分号样式的注释

一些文本编辑器根据开始评论的分号数量对所需的缩进进行假设.以下样式约定很常见,但绝不是通用的.

2.4.4.2.1单分号的使用

以单个分号开头的注释都与右侧的同一列对齐(有时称为"注释列").此类评论的文本通常仅适用于其出现的行.偶尔有两三个一起包含一个句子; 这有时通过缩进除第一个以外的所有空间(分号后)来表示.

2.4.4.2.2双分号的使用

以双分号开头的注释都与同一级别的缩进对齐,因为表单将位于代码中的相同位置.这种评论的文本通常描述评论发生时的程序状态,评论后面的代码,或两者.

2.4.4.2.3三分号的使用

以三分号开头的注释都与左边距对齐.通常它们在定义或定义集之前使用,而不是在定义中使用.

2.4.4.2.4使用四重分号

以四元分号开头的注释都与左边距对齐,并且通常只包含一小段文本作为后面代码的标题,并且可能用于准备代码的程序的页眉或页脚中用于呈现为硬拷贝文档.

2.4.4.2.5分号样式的例子

;;;; Math Utilities

;;; FIB computes the the Fibonacci function in the traditional
;;; recursive way.

(defun fib (n)
  (check-type n integer)
  ;; At this point we're sure we have an integer argument.
  ;; Now we can get down to some serious computation.
  (cond ((< n 0)
         ;; Hey, this is just supposed to be a simple example.
         ;; Did you really expect me to handle the general case?
         (error "FIB got ~D as an argument." n))
        ((< n 2) n)             ;fib[0]=0 and fib[1]=1
        ;; The cheap cases didn't work.
        ;; Nothing more to do but recurse.
        (t (+ (fib (- n 1))     ;The traditional formula
              (fib (- n 2)))))) ; is fib[n-1]+fib[n-2].

Answer 2

多行评论#| |#通常用于注释掉大量的Lisp代码或示例代码.由于一些Emacs实现似乎无法解析它们,因此有些正在使用#|| ||#而不是.

对于使用分号看到评论例如书籍的Common Lisp语言(页348),1984年,数字印刷,由Guy L. Steele的小:

;;;; COMMENT-EXAMPLE function. 
;;; This function is useless except to demonstrate comments. 
;;; (Actually, this example is much too cluttered with them.) 

(defun comment-example (x y)      ;X is anything; Y is an a-list. 
  (cond ((listp x) x)             ;If X is a list, use that. 
        ;; X is now not a list.  There are two other cases. 
        ((symbolp x) 
        ;; Look up a symbol in the a-list. 
        (cdr (assoc x y)))        ;Remember, (cdr nil) is nil. 
        ;; Do this when all else fails: 
        (t (cons x                ;Add x to a default list. 
                 '((lisp t)       ;LISP is okay. 
                   (fortran nil)  ;FORTRAN is not. 
                   (pl/i -500)    ;Note that you can put comments in 
                   (ada .001)     ; "data" as well as in "programs". 
                   ;; COBOL?? 
                   (teco -1.0e9))))))

在此示例中,注释可以以一到四个分号开头.

• 单分号注释全部与右侧的同一列对齐; 通常每个评论只涉及它旁边的代码.偶尔评论的时间足以占据两三行; 在这种情况下,通常将注释的连续行缩进一个空格(在分号之后).

• 双分号注释与代码的缩进级别对齐.一个空间通常遵循两个分号.这些注释通常描述该点的程序状态或注释后面的代码部分.

• 三分号注释与左边距对齐.它们通常记录整个程序或大型代码块.

• 四分号注释通常表示整个程序或大代码块的标题.

Answer 3

Common Lisp风格的标准参考,包括评论惯例,是Peter Norvig和Kent Pitman的Good Lisp编程风格教程.

Answer 4

而不是在这里描述,看看这个页面.它正在讨论Emacs Lisp,但所有lisps(和方案)的约定都是相同的.

Answer 5

当人们谈论约定却没有真正解释在行尾注释中混合使用双分号和单分号有什么问题时，这是很烦人的。“惯例说……等等……”。但到底为什么这么说呢？这就是众所周知的“祖母法则”的由来。“为什么我们要这样做？嗯，因为我们的奶奶是这样教我们的，而且她对此非常严格......”:)

大多数时候，在所谓的“边距”（行尾）注释中使用双分号不会有问题。如果您在同一个块中混合边距注释和常规注释，这可能会成为一个问题，例如：

   (defn foo []
      (bar) ;; yup, bar
      ;; let's now do a zap
      (zap))

因此，如果您使用fill-paragraphEmacs 的功能 - 它会自动对齐这些注释，就好像它们是单个语句一样。

   (defn foo []
      (bar) ;; yup, bar
            ;; let's now do a zap
      (zap))

这可能不是您想要的。因此，如果您使用单个分号代替：

   (defn foo []
      (bar) ; yup, bar
      ;; let's now do a zap
      (zap))

它将使它们保持预期的状态（未对齐）。因此，我猜人们只是制定了一条规则，而不是一遍又一遍地解释这一点 -在边距注释中使用单个分号