web-dev-qa-db-ja.com

Lispコメント規約

さまざまな種類のコメントに使用するセミコロンの数に関するLISPの規則は何ですか（また、さまざまな数のセミコロンのインデントのレベルはどうあるべきですか）。

また、セミコロンコメントを使用するタイミングと#|multiline comments|#を使用するタイミングに関する規則はありますか？

commentslispcommon-lispconventions
60
compman

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)に変更するか、実際にその式に必要な一連の機能を実際に含めることで、簡単に編集できることです。読んでください。

SLIMEは、LISPを実行しているときに、フォーム_(do-something a)_をコメントとしてフォント化することで役立ちます。

_#| |#_や#+(or)などのCommon LISPの特定のコメント構文とトリック、またはより一般的に見られる_#+nil_は別として、セミコロンルールは他のlispsでも広く採用されていると思います。

仕様 からの抜粋です。単一のセミコロンに関して現在の慣行がどのように分かれているかに注意してください。

2.4.4.2セミコロンのスタイルに関する注意

一部のテキストエディターは、コメントを開始するセミコロンの数に基づいて、必要なインデントについて仮定します。次のスタイル規則は一般的ですが、決して普遍的ではありません。

2.4.4.2.1単一セミコロンの使用

単一のセミコロンで始まるコメントはすべて、右側の同じ列（「コメント列」と呼ばれることもあります）に揃えられます。通常、このようなコメントのテキストは、コメントが表示される行にのみ適用されます。時折、2つまたは3つに単一の文が含まれる場合があります。これは、最初のスペースを除くすべてのスペースを追加のスペース（セミコロンの後）でインデントすることで示される場合があります。

2.4.4.2.2ダブルセミコロンの使用

フォームがコード内の同じ位置にあるため、ダブルセミコロンで始まるコメントはすべて同じレベルのインデントに揃えられます。通常、このようなコメントのテキストは、コメントが発生した時点でのプログラムの状態、コメントに続くコード、またはその両方を記述します。

2.4.4.2.3トリプルセミコロンの使用

トリプルセミコロンで始まるコメントはすべて左マージンに揃えられます。通常、それらは定義内ではなく、定義または一連の定義の前に使用されます。

2.4.4.2.4四重セミコロンの使用

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].
_
63
acelent

複数行コメント＃| |＃は、多くのLISPコードまたはサンプルコードをコメントアウトするためによく使用されます。一部のEmacs実装では解析に問題があるように見えるため、一部は＃||を使用しています。 ||＃代わりに。

セミコロンの使用については、本のコメント例を参照してくださいCommon LISP the Language（348ページ）、1984年、Digital Press、Guy L. Steele Jr .:

;;;; 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))))))

この例では、コメントは1〜4個のセミコロンで始まる場合があります。

  • 単一セミコロンのコメントはすべて、右側の同じ列に配置されます。通常、各コメントは隣のコードのみに関係します。コメントが2、3行を占めるほど長い場合があります。この場合、コメントの継続行を1スペース（セミコロンの後）インデントするのが一般的です。

  • ダブルセミコロンのコメントは、コードのインデントのレベルに合わせて調整されます。通常、2つのセミコロンの後にスペースが続きます。通常、このようなコメントは、その時点でのプログラムの状態、またはコメントに続くコードセクションを記述します。

  • トリプルセミコロンのコメントは左マージンに揃えられます。通常、プログラム全体または大きなコードブロックを文書化します。

  • 4重セミコロンコメントは通常、プログラム全体のタイトルまたは大きなコードブロックを示します。

29
Rainer Joswig

コメント規則を含むCommon LISPスタイルの標準リファレンスは、Peter NorvigとKent Pitmanの Tutorial on Good LISP Programming Style です。

8
Peter S. Housel

ここで説明する代わりに、 このページ をご覧ください。 Emacs LISPについて話していますが、規則はすべてのlisps（およびスキーム）で同じです。

6
Eli Barzilay

行末のコメントでダブルセミコロンを使用することの何が悪いのかを説明せずに、人々が規則を参照するのは面倒です。

いわゆる「マージン」（行末）コメントでダブルセミコロンを使用しても、それ自体に問題はありません。ただし、同じブロックにマージンコメントと通常のコメントを含める場合は、問題になる場合があります。

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

したがって、fill-paragraph Emacsの機能-これらのコメントを単一のステートメントであるかのように自動的に整列させます。

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

そして、それはおそらくあなたが望むものではありません。そのため、代わりに単一のセミコロンを使用する場合：

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

意図したとおりに保持されます。代わりにこれを何度も説明する代わりに、人々は規則を作っただけだと思う​​-マージンコメントにはセミコロンを使用

1
iLemming