comments lisp common-lisp conventions

comments - Lisp commenting convention



common-lisp conventions (4)

¿Cuál es la convención de Lisp sobre cuántos puntos y comas usar para diferentes tipos de comentarios (y cuál debe ser el nivel de sangría para varios números de punto y coma)?

Además, ¿existe alguna convención sobre cuándo usar los comentarios de punto y coma y cuándo usar #|multiline comments|# (suponiendo que existan y existan en múltiples implementaciones)?

Comentarios multilínea # | | # a menudo se usan para comentar grandes cantidades de código Lisp o código de ejemplo. Como algunas implementaciones de Emacs parecen tener problemas para analizarlas, algunas están usando # || || # en su lugar.

Para el uso de punto y coma, vea el ejemplo de comentario en el libro Common Lisp the Language (página 348), 1984, Digital Press, por 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))))))

En este ejemplo, los comentarios pueden comenzar con uno a cuatro puntos y comas.

  • Los comentarios de un solo punto y coma están todos alineados a la misma columna a la derecha; por lo general, cada comentario se refiere solo al código al que está relacionado. Ocasionalmente, un comentario es lo suficientemente largo como para ocupar dos o tres líneas; en este caso, es convencional sangrar las líneas continuas del comentario en un espacio (después del punto y coma).

  • Los comentarios de doble punto y coma están alineados con el nivel de sangría del código. Un espacio convencionalmente sigue los dos puntos y comas. Tales comentarios generalmente describen el estado del programa en ese punto o la sección de código que sigue al comentario.

  • Los comentarios de punto y coma triple están alineados con el margen izquierdo. Usualmente documentan programas completos o bloques de códigos grandes.

  • Los comentarios de punto y coma cuádruple generalmente indican títulos de programas completos o bloques de códigos grandes.

En 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

Nota: Emacs no crea fuentes #| |# #| |# muy bien, pero como sugiere Rainer en los comentarios, intenta usar #|| ||# #|| ||# lugar.

Diría que no hay reglas para usar esta, pero creo que es más rápido para comentar grandes cantidades de código, o para insertar una descripción larga donde los puntos y comas solo se interponen en el modo de edición, como grandes listados de BNF o similares.

Hay un buen truco para deshabilitar el código que es para prefijar una expresión con #+(or) :

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

Nota: #+nil generalmente también funciona, a menos que tenga una función nil o :nil . La ventaja de #+(or) es que puede editarlo fácilmente ya sea comentándolo o cambiándolo a #+(and) , o para incluir realmente un conjunto de características sobre las que realmente desea que se lea esa expresión.

SLIME ayuda aquí mediante la creación de la forma (do-something a) como un comentario cuando se ejecuta un Lisp.

Además de la sintaxis y los trucos particulares de Common Lisp, como #| |# #| |# y #+(or) o el más visto #+nil , creo que las reglas de punto y coma son ampliamente adoptadas en otros ceceos también.

Aquí hay un extracto de la especificación , observe cómo la práctica actual ha divergido con respecto al punto y coma único:

2.4.4.2 Notas sobre el estilo para punto y coma

Algunos editores de texto hacen suposiciones sobre la indentación deseada en función de la cantidad de puntos y comas que comienzan un comentario. Las siguientes convenciones de estilo son comunes, aunque de ningún modo universales.

2.4.4.2.1 Uso de Single Semicolon

Los comentarios que comienzan con un solo punto y coma están todos alineados con la misma columna a la derecha (a veces llamada la "columna de comentarios"). El texto de dicho comentario generalmente se aplica solo a la línea en la que aparece. Ocasionalmente dos o tres contienen una sola oración juntas; esto a veces se indica al sangrar todos menos el primero con un espacio adicional (después del punto y coma).

2.4.4.2.2 Uso de Double Semicolon

Los comentarios que comienzan con un punto y coma doble están todos alineados con el mismo nivel de sangría que un formulario en la misma posición en el código. El texto de dicho comentario generalmente describe el estado del programa en el momento en que se produce el comentario, el código que sigue al comentario o ambos.

2.4.4.2.3 Uso de Triple Semicolon

Los comentarios que comienzan con un punto y coma triple están alineados con el margen izquierdo. Por lo general, se usan antes de una definición o conjunto de definiciones, en lugar de dentro de una definición.

2.4.4.2.4 Uso de Cuádruple Punto y coma

Los comentarios que comienzan con un punto y coma cuádruple están alineados con el margen izquierdo, y generalmente contienen solo una pequeña porción de texto que sirve como título para el código que sigue, y pueden usarse en el encabezado o pie de página de un programa que prepara el código para presentación como un documento impreso.

2.4.4.2.5 Ejemplos de estilo para punto y coma

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

En lugar de describirlo aquí, eche un vistazo a esta página . Está hablando de Emacs Lisp, pero la convención es la misma en todos los lisps (y esquemas).