Lisp commentant la convention
Quelle est la convention LISP concernant le nombre de points-virgules à utiliser pour différents types de commentaires (et quel doit être le niveau d'indentation pour différents nombres de points-virgules)?
De même, existe-t-il une convention sur le moment où utiliser des commentaires point-virgule et le moment d'utiliser #|multiline comments|# (en supposant qu'ils existent et existent sur plusieurs implémentations)?
En LISP commun:
;;;; 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
Remarque: Emacs n'utilise pas très bien le code #| |#, mais comme Rainer le suggère dans les commentaires, essayez plutôt d'utiliser #|| ||#.
Je dirais qu'il n'y a pas de règles pour utiliser celle-ci, mais je pense que c'est plus rapide pour commenter d'énormes quantités de code, ou pour insérer une description longue où les points-virgules sont un obstacle à l'édition, comme les énormes listes BNF ou autres.
Il existe une astuce intéressante 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 possédez une fonctionnalité nil ou :nil. L’avantage de #+(or) est que vous pouvez le modifier facilement en le commentant ou en le changeant en #+(and), ou en incluant un ensemble de fonctionnalités sur lesquelles vous voulez vraiment que cette expression soit lue.
SLIME aide ici en rendant le formulaire (do-something a) en tant que commentaire lorsque vous avez un LISP en cours d'exécution.
Outre la syntaxe de commentaire et les astuces particulières de Common LISP, telles que #| |# et #+(or) ou le plus communément observé #+nil, je pense que les règles de point-virgule sont également largement adoptées dans les autres scripts.
Voici un extrait de le cahier des charges , remarquez comment la pratique actuelle a divergé en ce qui concerne le point-virgule unique:
2.4.4.2 Remarques 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 courantes, même si elles ne sont en aucun cas universelles.
2.4.4.2.1 Utilisation d'un seul point-virgule
Les commentaires qui commencent par un seul point-virgule sont tous alignés sur la même colonne à droite (parfois appelée «colonne de commentaires»). 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 ensemble; ceci est parfois indiqué en indentant tout sauf le premier avec un espace supplémentaire (après le point-virgule).
2.4.4.2.2 Utilisation du double point-virgule
Les commentaires commençant par un double point-virgule sont tous alignés sur le même niveau d'indentation qu'un formulaire se trouverait à la même position dans le code. Le texte d'un tel commentaire décrit généralement l'état du programme au point où le commentaire se produit, le code qui suit le commentaire ou les deux.
2.4.4.2.3 Utilisation du triple point-virgule
Les commentaires commençant par un triple point-virgule sont tous alignés sur la marge de gauche. Ils sont généralement 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 point-virgule quadruple
Les commentaires commençant par un point-virgule quadruple sont tous alignés sur la marge de gauche et ne contiennent généralement qu'un court morceau de texte servant de titre au code suivant, et pouvant être utilisé dans l'en-tête ou le pied de page d'un programme qui prépare le code. pour la présentation sous forme de 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 de code exemple. Certaines implémentations d’Emacs semblant avoir du mal à les analyser, d’autres 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 (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))))))
Dans cet exemple, les commentaires peuvent commencer par un à quatre points-virgules.
Les commentaires sur un seul point-virgule sont tous alignés sur la même colonne à droite; généralement, 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 un espace (après le point-virgule).
Les commentaires à 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 stade ou la section de code qui suit le commentaire.
Les commentaires en triple point-virgule sont alignés sur la marge de gauche. Ils documentent généralement des programmes entiers ou des blocs de code volumineux.
Les commentaires en quadruple point-virgule indiquent généralement les titres de programmes complets ou de gros blocs de code.
Peter Norvig et Didacticiel sur le bon style de programmation LISP .
Au lieu de la décrire ici, regardez cette page . Il s'agit d'Emacs LISP, mais la convention est la même pour tous les programmes (et schémas).
Il est agaçant que les gens se réfèrent aux conventions sans expliquer ce qui ne va pas avec l’utilisation de points-virgules doubles avec des commentaires de fin de ligne.
Il n'y a rien de mal en soi à utiliser des doubles points-virgules avec des commentaires dits "de marge". Cela peut devenir un problème si vous voulez avoir des commentaires de marge et des commentaires réguliers dans le même bloc, par exemple:
(defn foo []
(bar) ;; yup, bar
;; let's now do a zap
(zap))
Donc, si vous utilisez la fonctionnalité fill-paragraph de Emacs, les deux commentaires seront automatiquement alignés comme s’il s’agissait d’une seule déclaration.
(defn foo []
(bar) ;; yup, bar
;; let's now do a zap
(zap))
Et ce n'est pas ce que vous voulez probablement. Donc, si vous utilisez un seul point-virgule à la place:
(defn foo []
(bar) ; yup, bar
;; let's now do a zap
(zap))
Il le gardera comme prévu. Donc, au lieu d’expliquer cela maintes et maintes fois, je suppose que les gens viennent d’énoncer une règle - utilisez un seul point-virgule pour les commentaires de marge