Lua

Question

我正在寻找一种方法来澄清我的Lua函数的合同。特别是，参数应该具有哪些属性。

为了说明我的问题，一些代码片段具有我当前代码的典型结构。一个用两个公共函数构造一个新“实例”的函数。

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)

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

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

我更喜欢一种轻量级的方法，而不是尝试模拟基于类的继承。同样，代码比文档更受欢迎，如果不这样做，工具理解的格式的文档优先于自由格式。显然，我可以写一个评论，例如“参数newTextPrinter需要textPrinter和print公共函数”，但是如果没有任何内容告诉您在文档中犯的错误，或者非常容易出错，或者当你重构代码并忘记更新代码时。

我正在使用Lua 5.0并且对这门语言很陌生。

Answer 1

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

有一些格式化的评论处理系统：LuaDoc，LDoc，LDT文档语言，....遗憾的是，没有标准，选择主要取决于用户IDE的功能。某些IDE甚至可以帮助作者格式化注释。

即使没有处理，标签和格式化 - 大部分 - 都提高了人类的可读性。因此，只要源很容易弹出，它确实有帮助。