Lua 中的自记录参数

Question

我正在寻找一种方法来阐明我的 Lua 函数的契约。特别是那里的参数应该具有哪些属性。

为了说明我的问题，一些代码片段具有我当前代码的典型结构。构造一个新的 "instance" 和两个 public 函数的函数。

local function newTextPrinter(color)
    return {
        print = function(textToPrint)
            PrintText(textToPrint, 20, color, 5, 'center');
        end,
        printBig = function(textToPrint)
            PrintText(textToPrint, 30, color, 5, 'center');
        end
    }
end

一个函数，其参数应该具有相同的签名（或超集）。

local function printSomeStuff(textPrinter)
    textPrinter.print("some")
    textPrinter.printBig("stuff")
end

后面函数的调用

local textPrinter = newTextPrinter("ffffffff")
printSomeStuff(textPrinter)

此代码的问题在于，如果不查看 printSomeStuff 的实现，您将无法判断提供给 printSomeStuff 的 textPrinter 参数应该是什么样子。虽然在这个例子中这样做很容易，但通常情况并非如此（在我的场景中强制在文件之间跳转）。除了名称相似之外，也没有提示可以通过 newTextPrinter 获得合适的值。

有没有办法让代码更加自我记录并更好地揭示作者的意图？

我更喜欢一种轻巧的方法，并且不会尝试模仿基于 class 的继承。同样，代码优于文档，否则，工具理解格式的文档优于自由格式。很明显，我可以只写像 "parameter textPrinter needs print and printBig public functions" 这样的注释，但是如果没有任何内容告诉您您在文档中犯的错误，或者当您重构代码而忘记更新它时，这很容易出错。

我使用的是 Lua 5.0，对这门语言还很陌生。

Answer 1

是的。首先，命名是关键。接下来，评论可以描述合同。此外，格式化、标记、处理和上下文呈现的评论是多少人编程的。最后，格式化注释中的超链接提供了访问完整文档的途径。

有一些格式化注释处理系统：LuaDoc、LDoc、LDT 文档语言……。不幸的是，没有标准，选择主要取决于用户 IDE 的能力。一些 IDE 甚至会协助作者格式化评论。

即使不进行处理，标记和格式化（在很大程度上）也提高了人类的可读性。所以只要源码容易弹出，还是有帮助的。

Lua 中的自记录参数

Self documenting parameters in Lua

lua

types

self-documenting-code

readability

code-documentation