Конвенции комментируя сюсюкать

В 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

Примечание: Emacs не fontify #| |# очень хорошо, но как Райнер говорит в комментариях, попробуйте использовать .

я бы сказал, что нет правил для использования этого, но я считаю, что это быстрее для комментирования огромного количества кода или для вставки некоторого длинного описания, где точки с запятой просто мешают редактированию, например, огромные списки BNF или тому подобное.

есть аккуратный трюк, чтобы отключить код, который должен префикс выражение с #+(or):

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

Примечание: #+nil обычно тоже работает, если у вас есть nil или :nil характеристика. Преимущество #+(or) это то, что вы можете легко редактировать его, либо комментируя его или изменить его на #+(and), или фактически включить набор функций, на которых вы действительно хотите, чтобы это выражение было прочитано.

слизь помогает здесь, фонтифицируя форму (do-something a) как комментарий, когда у вас есть Лисп работает.

помимо Особый синтаксис комментариев 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].