Lisp评论惯例 [英] Lisp commenting convention

问题描述

什么是关于有多少个分号用于不同种类的评论（以及各种分号的缩进级别应该是什么）的Lisp约定是什么？此外，是否有关于何时使用分号注释和何时使用＃|多行注释|＃（假定它们存在并存在于多个实现上）的任何约定。

What is the Lisp convention about how many semicolons to use for different kinds of comments (and what the level of indentation for various numbers of semicolons should be)? Also, is there any convention about when to use semicolon comments and when to use #|multiline comments|# (assuming they exist and exist on multiple implementations)?

推荐答案

在Common Lisp中：

In 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不fontify ＃| |＃非常好，但是像Rainer在评论中建议的，尝试使用＃|| ||＃。

Note: Emacs doesn't fontify #| |# very well, but as Rainer suggests in the comments, try using #|| ||# instead.

我想说没有规则可以使用这个，但我估计它更快的评论大量代码，或插入一些长的描述，其中的分号正在编辑的方式，如巨大的BNF列表等。

I'd say there are no rules to use this one, but I reckon it's faster for commenting huge amounts of code, or to insert some long description where the semicolons just get in the way of editing, like huge BNF listings or the like.

有一个整洁的技巧，禁用代码是以＃+（或）为前缀的表达式：

There's a neat trick to disable code which is to prefix an expression with #+(or):

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

注意：＃+ nil 通常也有效，除非你碰巧有 nil 或：nil 功能。 ＃+（或）的优点在于您可以轻松地将其注释或将其更改为＃+（和），或者实际上包含一组你真正想要读取该表达式的特征。

Note: #+nil usually works too, unless you happen to have a nil or :nil feature. The advantage of #+(or) is that you can edit it easily by either commenting it out or change it to #+(and), or to actually include a set of features upon which you really want that expression to be read.

SLIME通过将<$ c

SLIME helps here by fontifying the form (do-something a) as a comment when you have a Lisp running.

除了Common Lisp的特殊注释语法和技巧之外，还有一个注释是$ c>（do-something a） ，例如＃| |＃和＃+（或）或更常见的＃+ nil

Apart from Common Lisp's particular commenting syntax and tricks, such as #| |# and #+(or) or the more commonly seen #+nil, I believe the semicolon rules are widely adopted in other lisps too.

这里是摘录自规范，请注意当前实践对于单个分号的分歧：

Here's an excerpt from the specification, note how current practice has diverged regarding the single semicolon:

2.4.4.2有关分号风格的注意事项

一些文本编辑器根据开始评论的分号。

2.4.4.2 Notes about Style for Semicolon

Some text editors make assumptions about desired indentation based on the number of semicolons that begin a comment. The following style conventions are common, although not by any means universal.

以单个分号开头的注释都对齐到右侧的相同列（有时称为注释列）。这样的注释的文本通常只适用于它出现的行。偶尔两三个一起包含一句话;

Comments that begin with a single semicolon are all aligned to the same column at the right (sometimes called the "comment column"). The text of such a comment generally applies only to the line on which it appears. Occasionally two or three contain a single sentence together; this is sometimes indicated by indenting all but the first with an additional space (after the semicolon).

以双分号开头的注释都对齐到相同的缩进级别，因为表单会在代码中的同一位置。这样的注释的文本通常描述在发生注释时的程序的状态，注释后的代码，或两者。

Comments that begin with a double semicolon are all aligned to the same level of indentation as a form would be at that same position in the code. The text of such a comment usually describes the state of the program at the point where the comment occurs, the code which follows the comment, or both.

以三个分号开头的注释都与左边距对齐。

Comments that begin with a triple semicolon are all aligned to the left margin. Usually they are used prior to a definition or set of definitions, rather than within a definition.

以四分号开头的注释都与左边距对齐，并且通常只包含一小段文本，作为后面代码的标题，并可能在标题中使用

Comments that begin with a quadruple semicolon are all aligned to the left margin, and generally contain only a short piece of text that serve as a title for the code which follows, and might be used in the header or footer of a program that prepares code for presentation as a hardcopy document.

;;;; 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].

这篇关于Lisp评论惯例的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！