functional-programming - 函数式编程的正确注释

Question

我一直在学习scheme，但我才意识到我真的不知道如何正确注释我的功能scheme代码。我当然知道如何添加评论 - 你添加 ;并在其后发表您的评论。我的问题是我应该在我的评论中放什么，我应该在哪里评论以获得最大的可读性和可理解性，以便其他程序员阅读我的代码？

这是我写的代码片段。这是一个名为 display-n 的函数.可以使用任意数量的参数调用它，并按照提供的顺序将每个参数输出到屏幕。

(define display-n
  (lambda nums
    (letrec ((display-n-inner 
              (lambda (nums)
                (display (car nums))
                (if (not (equal? (cdr nums) (quote ()))
                    (display-n-inner (cdr nums))))))
      (display-n-inner nums))))

编辑:改进标签并替换 '()与 (quote ())以免弄乱格式。

我只是不确定如何/在哪里添加评论以使其更易于理解。我见过的一些方案代码只是在顶部有注释，如果您想使用该代码，这很好，但如果您想理解/修改它，则无济于事。

另外 - 我应该如何评论宏？

Answer 1

Lisp 注释的常见样式是

四个分号用于对文件的整个小节进行评论。

三个分号用于介绍单个程序。

下一行的表达式/过程定义的描述用两个分号。

一个分号用于结束注释。

过程概述注释可能应该遵循 RnRS 文档的风格，因此只需按原样向过程添加注释，看起来像

;;;程序:显示-n NUM ...
;;按照提供的顺序将每个参数输出到屏幕。
(定义
display-n (lambda nums
(letrec ((display-n-inner (lambda (nums)
(显示(车号))
(if (not (equal? (cdr nums) '()))
(display-n-inner (cdr nums))))))
(display-n-inner nums))))

注意我没有在整个过程描述中使用三个分号，因为它搞砸了 Emacs 中的填充段落。

现在关于代码，我会放弃整个定义变量作为 lambda 的事情。是的，我知道这是定义函数的“最纯粹”的方式，它与定义过程的良好一致性是 LET 和其他过程的结果，但是语法糖是有原因的，它是为了让事情更可读。 LETREC 也是一样——只需使用内部 DEFINE，它是相同的，但更具可读性。

DISPLAY-N-INNER 的参数被称为 NUMS 并不是什么大不了的事，因为该过程很短，而 DISPLAY-N 只是直接将其 NUMS 交给它。不过，“DISPLAY-N-INNER”这个名字有点蹩脚。你会给它一些具有更多语义意义的东西，或者给它一个简单的名字，比如“ITER”或“LOOP”。

现在关于程序的逻辑。一、 (equal? (cdr nums) '())很傻，不如 (null? (cdr nums)) .实际上，当您对整个列表进行操作时，最好将基本情况作为列表本身而不是其 CDR 是否为空的测试。这样，如果您不传递任何参数，该过程就不会出错(除非您希望它这样做，但我认为如果 DISPLAY-N 什么都不做，则它什么都不做更有意义)。此外，您应该测试是否停止该过程，而不是是否继续:

(定义 (display-n . nums)
(定义(迭代编号)
(如果(空？nums)
#t ;它返回什么并不重要。
(开始(显示(车号))
(iter (cdr nums)))))
(迭代编号))

但尽管如此，我会说程序本身并不是完成它所做任务的最佳方式，因为它过于关注遍历列表的细节。相反，您将使用更抽象的 FOR-EACH 方法来完成这项工作。

(定义 (display-n . nums)
(对于每个显示编号))

这样，程序的读者就不会陷入 CAR 和 CDR 的细节中，而只需理解 FOR-EACH 将显示 NUMS 的每个元素。