5

I come from the strongly typed world and I want to write some Lua code. How should I document what type things are? What do Lua natives do? Hungarian notation? Something else?

For example:

local insert = function(what, where, offset)

It's impossible to tell at a glance whether we're talking about strings or tables here.

Should I do

local sInsert = function(sWhat, sWhere, nOffset)

or

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

or something else?

What about local variables? What about table entries (e.g. someThing.someProperty)?

Ansis Māliņš
  • 1,684
  • 15
  • 35
  • Code style is usually dictated by your employer. – Egor Skriptunoff Sep 04 '14 at 15:14
  • Document the source in the manner that your IDE supports for its content assistance and popover help. – Tom Blodget Sep 04 '14 at 16:53
  • Complicating the issue is that parameters are often polymorphic. A table key can be any type except `nil`. A table value can be any type. Some functions support tables or functions for certain parameters.... Your `where` is a potential case. – Tom Blodget Sep 04 '14 at 16:56
  • 1
    I've seen several times Haskell-style annotations (sort-of): `insert :: string -> number -> string`, etc. – michaelmeyer Sep 04 '14 at 19:03
  • There's a strong belief in "duck typing" among many Lua users. For example, if `what` needs to be a string, a table or userdata with an appropriate `_tostring()` metamethod associated is often just as acceptable. Being over-specific about type runs counter to that. – RBerteig Sep 08 '14 at 21:21

2 Answers2

4

For a reference on thoughts and opinions on Lua style in the community (or a particular community?), read this: LuaStyleGuide.

The closest one could get to an enforced style would be the format used by LuaDoc, as it's a fairly popular documentation generator used by high profile projects such as LuaFileSystem.

Rylander
  • 19,449
  • 25
  • 93
  • 144
Erik Pettis
  • 56
  • 1
0

There are only seven types in Lua.

Here are some conventions (some of them might sound a bit obvious; sorry):

  • Anything that sounds like a string, should be a string: street_address, request_method. If you are not sure you can add _name (or any other suffix that makes clear it's a substantive) to it: method_name
  • Anything that sounds like a number, should be a number: mass, temperature, percentage. When in doubt, add number, amount, coefficient, or whatever fits : number_of_children, user_id. The names n and i are usually given to numbers. If a number must be positive or natural, make assertions at the top of the function.
  • Boolean parameters are either an adjective (cold, dirty) or is_<adjective> (is_wet, is_ready).
  • Anything that sounds like a verb should be a function: consume, check. You can add _function, _callback or _f if you need to clarify it further: update_function, post_callback. The single letter f represents a function quite often. And usually you should only have one parameter of type function (recommended to put it at the end)
  • Anything that sounds like a collection should be a table: children, words, dictionary. People typically don't differentiate between array-like tables and dictionary-like tables, since both can be parsed with pairs. If you need to specify that a table is an array, you could add _array or _sequence at the end of the name. The letter t typically means table.
  • Coroutines are not used quite often; you can follow the same rules as with functions, and you can also add _cor to their names.
  • Any value can be nil.
    • If it's an optional value, initialize it at the top of the function: options = options or {}
    • If it's a mandatory value, make an assertion (or return error): assert(name, "The name is mandatory")
kikito
  • 51,734
  • 32
  • 149
  • 189