Надлежащий комментарий для функционального программирования

Некоторые случайные примечания:

• Традиционно в коде Scheme и Lisp использовались ;;; для комментариев верхнего уровня, ;; для комментариев в коде и ; для комментариев к той же строке, что и код, который они комментируют. Emacs поддерживает это, рассматривая каждый из них немного по-своему. Но особенно на стороне схемы это уже не так популярно, как было, но разница между ;; и ; по-прежнему распространена.

• В большинстве современных схем используются новые виды комментариев: theres:

  • # | ... | # для блочного комментария - полезно для длинных фрагментов текста, которые комментируют весь файл.
  • #; - это комментарий, который заставляет реализацию игнорировать выражение, что полезно для отладки.

• Что касается фактического содержания того, что писать, оно не отличается от любого другого языка, за исключением того, что при более функциональном подходе у вас обычно есть больше вариантов того, как разложить свой код. Это также делает более удобным написание более мелких функций, которые объединяются в более крупные функциональные возможности - и это также меняет стиль документации, поскольку многие такие небольшие функции будут «самодокументироваться» (в том смысле, что они легко читаются и очень очевидно, как они работают).

• Мне неприятно звучать как зажившая пластинка, но я все же считаю, что вам стоит потратить некоторое время на HtDP. Одна вещь, которую он поощряет в своем рецепте дизайна, - это сначала писать примеры, затем документацию, а затем расширять ее до реального кода.Кроме того, этот рецепт оставляет вам код с очень стандартным набором комментариев: типы ввода / вывода, формулировку цели, некоторую документацию о том, как реализована функция, когда это необходимо, и примеры можно рассматривать как другой вид документации ( который превратился бы в закомментированный код в «реальном» коде). (Есть и другие книги, которые занимают аналогичную позицию по отношению к документации.)

• Наконец, документирование макросов ничем не отличается от документирования любого другого кода. Единственное, что может сильно отличаться от того, что написано в комментариях: вместо описания того, что делает какая-то функция, вы склонны описывать, какой код она также расширяет , поэтому комментарии также больше относятся к мета-уровню . Общий подход к макросам заключается в минимальной работе внутри макроса - именно то, что необходимо на этом уровне (например, обернуть выражения в (lambda () ...) ), а фактическую реализацию оставить на функция. Это также помогает в документировании, поскольку в двух связанных частях будут комментарии о том, как макрос расширяется и как он выполняется независимо.

Я использую подход, похожий на тот, что выложен здесь:

http://www.cc.gatech.edu/computing/classes/cs2360/ghall/style/commenting.html

Примечание: это для Common Lisp.

Конкретно:

" Four Semicolons(;;;;)
...denote a sub heading in the file...

Three Semicolons(;;;)
...denote a description of the succeeding function, macro, or
variable definition...
[I usually just most of the description into the "docstring"
  of the function or variable.] 


 Two Semicolons(;;)
 ...denote a description of the succeeding expression...

 One Semicolon(;)
 ...denotes an in-line comment that explains a particular element
    of the expression on that line... Brevity is important for
    inline comments"

Я думаю, отличным местом для начала было бы поместить ваше односложное описание того, что делает функция

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

в качестве комментария в начале.

Я не особенно разбираюсь в схеме, поэтому не могу прокомментировать (:-)), ожидаются ли дополнительные построчные комментарии, объясняющие механику того, как функция достигает этого результата, в соответствии с обычным стилем схемы (но я подозреваю, что нет).