it-swarm.com.de

Lisp-Konvention kommentieren

Wie lauten die LISP-Konventionen, wie viele Semikolons für verschiedene Arten von Kommentaren verwendet werden sollen (und wie hoch die Einrückungsebene für verschiedene Anzahlen von Semikolons sein sollte)? 

Gibt es auch eine Konvention darüber, wann Semikolonkommentare verwendet werden sollen und wann #|multiline comments|# verwendet wird (vorausgesetzt, sie existieren und existieren in mehreren Implementierungen)?

57
compman

Im allgemeinen 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

Hinweis: Emacs kann #| |# nicht sehr gut formatieren, aber wie Rainer in den Kommentaren vorschlägt, verwenden Sie stattdessen #|| ||#.

Ich würde sagen, dass es keine Regeln gibt, um diese zu verwenden, aber ich denke, es ist schneller, um große Mengen an Code zu kommentieren oder eine lange Beschreibung einzufügen, an der die Semikolons gerade beim Editieren im Weg stehen, wie riesige BNF-Einträge oder ähnliches.

Es gibt einen netten Trick, um Code zu deaktivieren, der #+(or) einem Ausdruck vorangestellt ist:

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

Hinweis: #+nil funktioniert normalerweise auch, es sei denn, Sie haben eine nil- oder :nil-Funktion. Der Vorteil von #+(or) ist, dass Sie ihn leicht bearbeiten können, indem Sie ihn entweder auskommentieren oder in #+(and) ändern oder eine Reihe von Features einschließen, bei denen der Ausdruck wirklich gelesen werden soll.

SLIME hilft hier, indem Sie das Formular (do-something a) als Kommentar festlegen, wenn ein LISP ausgeführt wird.

Abgesehen von den speziellen Kommentarsyntax und -tricks von Common LISP, wie #| |# und #+(or) oder dem allgemeineren #+nil, glaube ich, dass die Semikolonregeln auch in anderen Lisps weit verbreitet sind.


Hier ist ein Auszug aus der Spezifikation . Beachten Sie, wie sich die derzeitige Praxis bezüglich des einzelnen Semikolons unterscheidet:

2.4.4.2 Hinweise zum Stil für Semikolon

Einige Texteditoren machen Annahmen über die gewünschte Einrückung basierend auf der Anzahl der Semikolons, die einen Kommentar beginnen. Die folgenden Stilkonventionen sind üblich, jedoch keinesfalls universell.

2.4.4.2.1 Verwendung eines einzelnen Semikolons

Kommentare, die mit einem einzelnen Semikolon beginnen, sind rechts auf die gleiche Spalte ausgerichtet (manchmal auch als "Kommentarspalte" bezeichnet). Der Text eines solchen Kommentars gilt im Allgemeinen nur für die Zeile, in der er erscheint. Gelegentlich enthalten zwei oder drei einen einzigen Satz zusammen; Dies wird manchmal angezeigt, wenn alle außer dem ersten mit einem zusätzlichen Leerzeichen (nach dem Semikolon) eingerückt werden.

2.4.4.2.2 Verwendung von doppeltem Semikolon

Kommentare, die mit einem doppelten Semikolon beginnen, sind alle auf dieselbe Einrückungsebene ausgerichtet, wie ein Formular an derselben Position im Code wäre. Der Text eines solchen Kommentars beschreibt normalerweise den Status des Programms an der Stelle, an der der Kommentar auftritt, der Code, der dem Kommentar folgt, oder beides.

2.4.4.2.3 Verwendung von Triple Semikolon

Kommentare, die mit einem dreifachen Semikolon beginnen, sind alle am linken Rand ausgerichtet. Normalerweise werden sie vor einer Definition oder einem Satz von Definitionen und nicht innerhalb einer Definition verwendet.

2.4.4.2.4 Verwendung von Quadruple Semicolon

Kommentare, die mit einem vierfachen Semikolon beginnen, sind alle am linken Rand ausgerichtet und enthalten im Allgemeinen nur einen kurzen Text, der als Titel für den folgenden Code dient. Er kann in der Kopf- oder Fußzeile eines Programms verwendet werden, das Code vorbereitet zur Vorlage als Papierdokument.

2.4.4.2.5 Stilbeispiele für Semikolon

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

Mehrzeilige Kommentare # | | # wird häufig verwendet, um größere Mengen an LISP-Code oder Beispielcode auszukommentieren. Da einige Emacs-Implementierungen Probleme beim Parsen haben, verwenden einige # || stattdessen || #.

Für die Verwendung von Semikolons siehe das Kommentarbeispiel im Buch Common LISP the Language (Seite 348), 1984, Digital Press, von 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))))))

In diesem Beispiel können Kommentare mit einem bis vier Semikolons beginnen.

  • Ein-Semikolon-Kommentare sind alle auf dieselbe Spalte rechts ausgerichtet. Normalerweise betrifft jeder Kommentar nur den Code, neben dem er steht. Gelegentlich ist ein Kommentar lang genug, um zwei oder drei Zeilen zu belegen. In diesem Fall ist es üblich, die fortgesetzten Zeilen des Kommentars um ein Leerzeichen (nach dem Semikolon) einzuziehen.

  • Doppel-Semikolon-Kommentare werden an die Einrückungsebene des Codes angepasst. Üblicherweise folgt ein Leerzeichen den zwei Semikolons. Solche Kommentare beschreiben normalerweise den Status des Programms an diesem Punkt oder den Codeabschnitt, der auf den Kommentar folgt.

  • Dreifach-Semikolon-Kommentare sind am linken Rand ausgerichtet. Sie dokumentieren in der Regel ganze Programme oder große Codeblöcke.

  • Quadrupel-Semikolon-Kommentare geben normalerweise Titel ganzer Programme oder großer Codeblöcke an.

29
Rainer Joswig

Die Standardreferenz für den Common LISP-Stil einschließlich der Kommentarkonventionen ist Peter Norvig und Kent Pitmans Tutorial über den guten LISP-Programmierstil .

8
Peter S. Housel

Anstatt es hier zu beschreiben, werfen Sie einen Blick auf diese Seite . Es geht um Emacs LISP, aber die Konvention ist in allen Lisps (und Schemata) gleich.

6
Eli Barzilay

Es ist ärgerlich, dass die Leute auf Konventionen verweisen, ohne zu erklären, was mit der Verwendung von doppelten Semikola mit Zeilenende-Kommentar falsch ist. 

Es ist nichts Falsches an der Verwendung von doppelten Semikolons mit sogenannten "margin" (Zeilenende) -Kommentaren. Es kann jedoch zu einem Problem werden, wenn im gleichen Block Randkommentare und reguläre Kommentare vorhanden sein sollen, z.

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

Wenn Sie also die fill-paragraph-Funktion von Emacs verwenden, werden beide Kommentare automatisch so ausgerichtet, als ob sie eine einzige Anweisung wären.

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

Und das wollen Sie wahrscheinlich nicht. Wenn Sie also ein einzelnes Semikolon verwenden,

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

Es wird es wie vorgesehen behalten. Statt dies immer wieder zu erklären, haben die Leute also eine Regel aufgestellt - verwenden Sie ein Semikolon für Randkommentare

0
iLemming