it-swarm.com.ru

Соглашение о комментировании на Лиспе

Что такое соглашение LISP о том, сколько точек с запятой следует использовать для комментариев разного типа (и каким должен быть уровень отступа для различного количества точек с запятой)? 

Кроме того, существует ли соглашение о том, когда использовать комментарии с точкой с запятой и когда использовать #|multiline comments|# (при условии, что они существуют и существуют в нескольких реализациях)?

57
compman

В общем 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.

Помимо специфического синтаксиса и уловок комментирования Common 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].
60
acelent

Многострочные комментарии # | | # часто используются для комментирования больших объемов кода LISP или примера кода. Поскольку некоторые реализации Emacs, похоже, испытывают проблемы с их анализом, некоторые используют # || || # вместо.

Для использования точек с запятой см. Пример комментария в книге Common LISP the Language (стр. 348), 1984, Digital Press, Гай Л. Стил-младший:

;;;; 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))))))

В этом примере комментарии могут начинаться с одной до четырех точек с запятой.

  • Комментарии, состоящие из одной точки с запятой, выровнены по одному столбцу справа; обычно каждый комментарий касается только кода, рядом с которым он находится. Иногда комментарий бывает достаточно длинным, чтобы занимать две или три строки; в этом случае условным отступом для продолжения строки комментария является один пробел (после точки с запятой).

  • Комментарии с двойной точкой с запятой выровнены по уровню отступа кода. Пространство условно следует за двумя точками с запятой. Такие комментарии обычно описывают состояние программы в тот момент или раздел кода, который следует за комментарием.

  • Комментарии в три точки с запятой выравниваются по левому краю. Они обычно документируют целые программы или большие блоки кода.

  • Комментарии с четырьмя точками с запятой обычно указывают заголовки целых программ или большие блоки кода.

29
Rainer Joswig

Стандартным справочником по общему стилю LISP, включая правила комментирования, является Питер Норвиг и Кент Питман Учебник по хорошему стилю программирования LISP .

8
Peter S. Housel

Вместо того, чтобы описать это здесь, взгляните на эту страницу . Речь идет о Emacs LISP, но соглашение одинаково для всех LISP (и схем).

6
Eli Barzilay

Раздражает, что люди ссылаются на условные обозначения, не объясняя, что не так с использованием двойных точек с запятой с комментариями в конце строки. 

Нет ничего плохого как такового в использовании двойных точек с запятой с так называемыми «полями» (в конце строки) комментариев. Это может стать проблемой, хотя, если вы хотите, чтобы комментарии на полях и регулярные комментарии были в одном блоке, например:

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

Итак, если вы используете функцию fill-paragraph в Emacs - она ​​автоматически выровняет оба этих комментария, как если бы они были одним оператором.

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

И это не то, что вы, вероятно, хотите. Так что, если вместо этого использовать одну точку с запятой:

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

Это сохранит это как предназначено. Поэтому вместо того, чтобы объяснять это снова и снова, я думаю, что люди просто создали правило - используйте одну точку с запятой для комментариев на полях

0
iLemming