Convention de commentaires Lisp

Quelle est la convention Lisp sur le nombre de points-virgules à utiliser pour différents types de commentaires (et quel devrait être le niveau d’indentation pour différents nombres de points-virgules)?

En outre, existe-t-il une convention concernant l’utilisation des commentaires par point-virgule et l’utilisation de #|multiline comments|# (en supposant qu’ils existent et existent sur plusieurs implémentations)?

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 

Note: Emacs ne pas spécifier #| |# #| |# très bien, mais comme Rainer le suggère dans les commentaires, essayez d’utiliser #|| ||# #|| ||# place.

Je dirais qu’il n’y a pas de règles pour utiliser celle-ci, mais je pense qu’il est plus rapide de commenter d’énormes quantités de code, ou d’insérer une longue description où les points-virgules gênent l’édition, comme les énormes listes BNF ou autres.

Il existe une astuce pour désactiver le code qui consiste à préfixer une expression avec #+(or) :

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

Remarque: #+nil fonctionne généralement aussi, sauf si vous avez une fonctionnalité nil ou :nil . L’avantage de #+(or) est que vous pouvez l’éditer facilement en le commentant ou en le remplaçant par #+(and) , ou pour inclure un ensemble de fonctionnalités sur lesquelles vous voulez vraiment que cette expression soit lue.

SLIME aide ici en définissant le formulaire (do-something a) comme un commentaire lorsque vous exécutez un Lisp.

En dehors de la syntaxe et des astuces de commentaire de Common Lisp, telles que #| |# #| |# et #+(or) ou le plus communément vu #+nil , je pense que les règles des points-virgules sont largement adoptées dans d’autres lisps.


Voici un extrait de la spécification , notez comment la pratique actuelle a divergé en ce qui concerne le point-virgule unique:

2.4.4.2 Notes sur le style pour le point-virgule

Certains éditeurs de texte émettent des hypothèses sur l’indentation souhaitée en fonction du nombre de points-virgules qui commencent un commentaire. Les conventions de style suivantes sont communes, mais pas du tout universelles.

2.4.4.2.1 Utilisation du point-virgule unique

Les commentaires qui commencent par un seul point-virgule sont tous alignés sur la même colonne à droite (parfois appelée «colonne de commentaire»). Le texte d’un tel commentaire ne s’applique généralement qu’à la ligne sur laquelle il apparaît. Parfois, deux ou trois contiennent une seule phrase; ceci est parfois indiqué en mettant en retrait tout sauf le premier avec un espace supplémentaire (après le point-virgule).

2.4.4.2.2 Utilisation du point-virgule double

Les commentaires qui commencent par un double point-virgule sont tous alignés sur le même niveau d’indentation qu’une forme serait à la même position dans le code. Le texte d’un tel commentaire décrit généralement l’état du programme au moment où le commentaire se produit, le code qui suit le commentaire ou les deux.

2.4.4.2.3 Utilisation du point-virgule sortingple

Les commentaires qui commencent par un point-virgule sortingple sont tous alignés sur la marge gauche. Habituellement, ils sont utilisés avant une définition ou un ensemble de définitions, plutôt que dans une définition.

2.4.4.2.4 Utilisation du Quadruple Semicolon

Les commentaires qui commencent par un point-virgule quadruple sont tous alignés sur la marge de gauche et ne contiennent généralement qu’un petit morceau de texte qui sert de titre au code qui suit, et qui peut être utilisé dans l’en-tête ou le pied de page d’un programme pour la présentation en tant que document papier.

2.4.4.2.5 Exemples de style pour le point-virgule

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

Commentaires multilignes # | | # sont souvent utilisés pour commenter de plus grandes quantités de code Lisp ou d’exemple. Comme certaines implémentations d’Emacs semblent avoir du mal à les parsingr, certaines utilisent # || || # à la place.

Pour l’utilisation des points-virgules, voir l’exemple de commentaire dans le livre Common Lisp the Language (page 348), 1984, Digital Press, par 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 (xy) ;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 xy))) ;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)))))) 

Dans cet exemple, les commentaires peuvent commencer par un à quatre points-virgules.

  • Les points-virgules simples sont tous alignés sur la même colonne à droite; En général, chaque commentaire ne concerne que le code à côté duquel il se trouve. Parfois, un commentaire est assez long pour occuper deux ou trois lignes; dans ce cas, il est classique d’indenter les lignes continues du commentaire d’un espace (après le point-virgule).

  • Les commentaires en double point-virgule sont alignés sur le niveau d’indentation du code. Un espace suit classiquement les deux points-virgules. Ces commentaires décrivent généralement l’état du programme à ce point ou la section de code qui suit le commentaire.

  • Les commentaires en sortingple point-virgule sont alignés sur la marge de gauche. Ils documentent généralement des programmes entiers ou de gros blocs de code.

  • Les commentaires quadruple-point-virgule indiquent généralement des titres de programmes entiers ou de gros blocs de code.

La référence standard pour le style Common Lisp, y compris les conventions de commentaires, est le Tutorial de Peter Norvig et Kent Pitman sur le bon style de programmation Lisp .

Au lieu de le décrire ici, consultez cette page . Il parle d’Emacs Lisp, mais la convention est la même pour tous les lisps (et schémas).