Lua中用于文档类型的约定是什么？

Question

我是从强类型世界来的，想写一些Lua代码。我应该如何记录事物的类型？Lua本身提供了哪些方式？使用匈牙利记号或其他方式？

例如：

local insert = function(what, where, offset)

很难一眼就看出这里是在说字符串还是表格。

我应该怎么办？

local sInsert = function(sWhat, sWhere, nOffset)

或者

-- string what, string where, number offset, return string
local insert = function(what, where, offset)

或者还有其他什么？

那么局部变量呢？表格条目呢（例如 someThing.someProperty）？

- Ansis Māliņš

---

代码风格通常由雇主决定。 - Egor Skriptunoff

记录源代码，并按照IDE支持的内容辅助和弹出式帮助的方式进行文档化。 - Tom Blodget

问题的复杂化在于参数通常是多态的。表键可以是除了 nil 以外的任何类型。表值可以是任何类型。一些函数支持表或函数作为某些参数...你的 where 是一个潜在的情况。 - Tom Blodget

我曾多次看到Haskell风格的注释（类似于）：insert :: string -> number -> string等。 - michaelmeyer

许多Lua用户坚信“鸭子类型”。例如，如果what需要是一个字符串，那么只要与适当的_tostring()元方法相关联的表或用户数据通常也是可以接受的。过于具体化类型与此相反。 - RBerteig

Answer 1

如果想了解社区（或特定社区）对Lua风格的想法和意见，请阅读此文：LuaStyleGuide。

最接近强制使用的风格可能是LuaDoc使用的格式，因为它是一个相当流行的文档生成器，被高知名度项目如LuaFileSystem使用。

- Erik Pettis

Answer 2

Lua 中只有七种类型。

以下是一些约定（其中一些可能听起来有点显而易见，抱歉）：

• 任何听起来像字符串的东西，都应该是字符串：street_address，request_method。如果你不确定，可以在它后面加上_name（或者其他明确表示它是实体的后缀）：method_name
• 任何听起来像数字的东西，都应该是数字：mass，temperature，percentage。当你不确定时，可以添加number，amount，coefficient或其他适合的词语：number_of_children，user_id。通常将n和i这样的字母用于数字。如果一个数字必须是正数或自然数，在函数顶部进行断言。
• 布尔参数要么是形容词（cold，dirty），要么是is_<adjective>（is_wet，is_ready）。
• 任何听起来像动词的东西都应该是一个函数：consume，check。如果需要进一步澄清，可以添加_function，_callback或_f：update_function，post_callback。单个字母f经常表示函数。通常你应该只有一个类型为函数的参数（建议将其放在最后）
• 任何听起来像集合的东西都应该是一个表格：children，words，dictionary。人们通常不区分类似数组的表和类似字典的表，因为两者都可以使用pairs解析。如果需要指定一个表是数组，可以在名称末尾添加_array或_sequence。字母t通常表示表。
• 协程并不经常使用；你可以遵循与函数相同的规则，也可以在它们的名称中添加_cor。
• 任何值都可以是nil。
  • 如果它是可选值，请在函数顶部初始化它：options = options or {}
  • 如果它是必需值，请进行断言（或返回错误）：assert(name, "The name is mandatory")

- kikito