Что такое соглашение Lisp о том, сколько точек с запятой использовать для разных видов комментариев (и каков уровень отступов для разных чисел с запятой)?
Кроме того, существует ли какое-либо соглашение о том, когда использовать комментарии с запятой и когда использовать #|multiline comments|# (предполагая, что они существуют и существуют во многих реализациях)?
В общем 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 не очень хорошо выделяет #| |#, но, как предлагает Райнер в комментариях, попробуйте вместо этого использовать #|| ||#.
Я бы сказал, что нет никаких правил для использования этого, но я считаю это быстрее для комментирования огромного количества кода или для вставки некоторого длинного описания, где точки с запятой просто мешают редактированию, например огромные списки BNF или.
Там аккуратный трюк, чтобы отключить код, который должен префикс выражения с помощью #+(or):
(defun test (a &optional b)
#+(or)
(do-something a)
(do-something-else b))
Примечание. #+nil обычно работает, если у вас нет функции nil или :nil. Преимущество #+(or) заключается в том, что вы можете легко его отредактировать, либо комментируя его, либо изменив его на #+(and), либо фактически включите набор функций, на которых вы действительно хотите, чтобы это выражение было прочитано.
SLIME помогает здесь, отформатируя форму (do-something a) как комментарий при запуске Lisp.
Помимо обычных Lisp специфических синтаксисов и трюков комментариев, таких как #| |# и #+(or), или более часто встречающихся #+nil, я считаю, что правила с запятой широко применяются и в других лисах.
Здесь выдержка из спецификация, обратите внимание на то, как текущая практика расходится в отношении одной точки с запятой:
2.4.4.2 Примечания о стилях для точки с запятой
Некоторые текстовые редакторы делают предположения о желаемом отступе на основе количества точек с запятой, которые начинают комментарий. Следующие соглашения стиля являются общими, хотя и не универсальными.
2.4.4.2.1 Использование одной точки с запятой
Комментарии, начинающиеся с одной точки с запятой, выравниваются по одному и тому же столбцу справа (иногда это называется столбцом комментариев). Текст такого комментария обычно применяется только к строке, на которой он появляется. Иногда два или три содержат одно предложение вместе; это иногда указывается отступом всех, кроме первого, с дополнительным пространством (после точки с запятой).
2.4.4.2.2 Использование двойной точки с запятой
Комментарии, начинающиеся с двойной точки с запятой, выравниваются с одинаковым уровнем отступов, так как форма будет в той же позиции в коде. Текст такого комментария обычно описывает состояние программы в точке, где происходит комментарий, код, следующий за комментарием, или и то, и другое.
2.4.4.2.3 Использование тройной точки с запятой
Комментарии, начинающиеся с тройной точки с запятой, выравниваются по левому краю. Обычно они используются до определения или набора определений, а не в определении.
2.4.4.2.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].
Многострочные комментарии # | | # часто используются для комментирования больших количеств кода Lisp или примерного кода. Поскольку некоторые реализации Emacs, похоже, имеют проблемы с их синтаксическим анализом, некоторые используют # || || # вместо.
Для использования точек с запятой см. пример комментария в книге Common Lisp 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))))))
В этом примере комментарии могут начинаться с одной-четырех точек с запятой.
Комментарии с одной точкой с запятой выравниваются по одному и тому же столбцу справа; обычно каждый комментарий касается только кода, который он рядом. Иногда комментарий достаточно длинный, чтобы занять две или три строки; в этом случае условно отступать от оставшихся строк комментария одним пространством (после точки с запятой).
Комментарии с двойной точкой с запятой выровнены с уровнем вдавливания кода. Пространство условно следует за двумя точками с запятой. Такие комментарии обычно описывают состояние программы в этой точке или раздел кода, следующий за комментарием.
Комментарии с тройной точкой с запятой выровнены по левому краю. Обычно они документируют целые программы или большие блоки кода.
Четырёхсекундные комментарии обычно указывают названия целых программ или больших кодовых блоков.
Стандартная ссылка для стиля Common Lisp, включая соглашения о комментариях, - это Питер Норвиг и Кент Питман Учебник по хорошему Lisp Стиль программирования.
Вместо описания здесь, посмотрите эту страницу. Он говорит о Emacs Lisp, но соглашение одинаково для всех lisp (и схем).
Раздражает, что люди обращаются к соглашениям, не объясняя, что не так с использованием двойных точек с запятой с комментариями в конце строки.
Нет ничего плохого как такового в использовании двойных точек с запятой с так называемыми "полями" (в конце строки) комментариев. Тем не менее, это может стать проблемой, если вы хотите, чтобы комментарии на полях и регулярные комментарии были в одном блоке, например:
(defn foo []
(bar) ;; yup, bar
;; let now do a zap
(zap))
Итак, если вы используете функцию fill-paragraph в Emacs - он автоматически выровняет оба этих комментария, как если бы они были одним оператором.
(defn foo []
(bar) ;; yup, bar
;; let now do a zap
(zap))
И это не то, что вы, вероятно, хотите. Так что, если вместо этого использовать одну точку с запятой:
(defn foo []
(bar) ; yup, bar
;; let now do a zap
(zap))
Это сохранит это как предназначено. Так что вместо того, чтобы объяснять это снова и снова, я думаю, что люди просто создали правило - используйте одну точку с запятой для комментариев на полях.