Lua style guide

Indentation and formatting

• 4 spaces instead of tabs. PIL suggests using two spaces, but a programmer looks at code from 4 to 8 hours a day, so it’s simpler to distinguish indentation with 4 spaces. Why spaces? Similar representation everywhere.

  Можно использовать строки режима (modelines) vim:

  -- vim:ts=4 ss=4 sw=4 expandtab
  

• Файл должен заканчиваться на один символ переноса строки, но не должен заканчиваться на пустой строке (два символа переноса строки).

• Отступы всех do/while/for/if/function должны составлять 4 пробела.

• Related or/and in if must be enclosed in the round brackets (). Example:

  -- Good
  if (a == true and b == false) or (a == false and b == true) then
      <...>
  end
  
  -- Bad
  if a == true and b == false or a == false and b == true then
      <...>
  end
  
  -- Good but not explicit
  if a ^ b == true then
  end
  

• Преобразование типов

  Не используйте конкатенацию для конвертации в строку или в число (вместо этого воспользуйтесь tostring/tonumber):

  -- Bad
  local a = 123
  a = a .. ''
  
  -- Good
  local a = 123
  a = tostring(a)
  
  -- Bad
  local a = '123'
  a = a + 5 -- 128
  
  -- Good
  local a = '123'
  a = tonumber(a) + 5 -- 128
  

• Постарайтесь избегать несколько вложенных if с общим телом оператора:

  -- Good
  if (a == true and b == false) or (a == false and b == true) then
      do_something()
  end
  
  -- Bad
  if a == true then
      if b == false then
          do_something()
      end
  if b == true then
      if a == false then
          do_something()
      end
  end
  

• Избегайте множества конкатенаций в одном операторе, лучше использовать string.format:

  -- Bad
  function say_greeting(period, name)
      local a = "good  " .. period .. ", " .. name
  end
  
  -- Good
  function say_greeting(period, name)
      local a = string.format("good %s, %s", period, name)
  end
  
  -- Best
  local say_greeting_fmt = "good %s, %s"
  function say_greeting(period, name)
      local a = say_greeting_fmt:format(period, name)
  end
  

• Используйте and/or для указания значений переменных, используемых по умолчанию,

  -- Good
  function(input)
      input = input or 'default_value'
  end
  
  -- Ok but excessive
  function(input)
      if input == nil then
          input = 'default_value'
      end
  end
  

• операторов if и возврата:

  -- Good
  if a == true then
      return do_something()
  end
  do_other_thing()
  
  -- Bad
  if a == true then
      return do_something()
  else
      do_other_thing()
  end
  

• Использование пробелов:

  • Don’t use spaces between function name and opening round bracket. Split arguments with one whitespace character:

    -- Bad
    function name (arg1,arg2,...)
    end
    
    -- Good
    function name(arg1, arg2, ...)
    end
    

  • Add a space after comment markers:

    while true do -- Inline comment
        -- Comment
        do_something()
    end
    --[[
    Multiline
    comment
    ]]--
    

  • Surrounding operators:

    -- Bad
    local thing=1
    thing = thing-1
    thing = thing*1
    thing = 'string'..'s'
    
    -- Good
    local thing = 1
    thing = thing - 1
    thing = thing * 1
    thing = 'string' .. 's'
    

  • Add a space after commas in tables:

    -- Bad
    local thing = {1,2,3}
    thing = {1 , 2 , 3}
    thing = {1 ,2 ,3}
    
    -- Good
    local thing = {1, 2, 3}
    

  • Add a space in map definitions after equals signs and commas:

    -- Bad
    return {1,2,3,4}
    return {
        key1 = val1,key2=val2
    }
    
    -- Good
    return {1, 2, 3, 4}
    return {
        key1 = val1, key2 = val2,
        key3 = val3
    }
    

    You can also use alignment:

    return {
        long_key  = 'vaaaaalue',
        key       = 'val',
        something = 'even better'
    }
    

  • Extra blank lines may be used (sparingly) to separate groups of related functions. Blank lines may be omitted between several related one-liners (for example, a set of dummy implementations).

    Use blank lines in functions (sparingly) to indicate logical sections:

    -- Bad
    if thing ~= nil then
        -- ... stuff ...
    end
    function derp()
        -- ... stuff ...
    end
    local wat = 7
    
    -- Good
    if thing ~= nil then
        -- ... stuff ...
    end
    
    function derp()
        -- ... stuff ...
    end
    
    local wat = 7
    

  • Delete whitespace at EOL (strongly forbidden. Use :s/\s\+$//gc in vim to delete them).

Avoid global variables

Avoid using global variables. In exceptional cases, start the name of such a variable with _G, add a prefix, or add a table instead of a prefix:

-- Very bad
function bad_global_example()
end

function good_local_example()
end
-- Good
_G.modulename_good_local_example = good_local_example

-- Better
_G.modulename = {}
_G.modulename.good_local_example = good_local_example

Always use a prefix to avoid name conflicts.

Именование

• Names of variables/»objects» and «methods»/functions: snake_case.
• Names of «classes»: CamelCase.
• Private variables/methods (future properties) of objects start with underscores <object>._<name>. Avoid syntax like local function private_methods(self) end.
• Boolean: naming is_<...>, isnt_<...>, has_, hasnt_ is good style.
• For «very local» variables:
  • t is for tables
  • i, j are for indexing
  • n is for counting
  • k, v is what you get out of pairs() (are acceptable, _ if unused)
  • i, v is what you get out of ipairs() (are acceptable, _ if unused)
  • k/key is for table keys
  • v/val/value is for values that are passed around
  • x/y/z is for generic math quantities
  • s/str/string is for strings
  • c is for 1-char strings
  • f/func/cb are for functions
  • status, <rv>.. or ok, <rv>.. is what you get out of pcall/xpcall
  • buf, sz is a (buffer, size) pair
  • <name>_p is for pointers
  • t0.. is for timestamps
  • err is for errors
• Abbreviations are acceptable if they’re very common or if they’re unambiguous and you’ve documented them.
• Global variables are spelled in ALL_CAPS. If it’s a system variable, it starts with an underscore (_G/_VERSION/..).
• Modules are named in snake_case (avoid underscores and dashes): for example, „luasql“, not „Lua-SQL“.
• *_mt and *_methods defines metatable and methods table.

Идиомы и шаблоны

Всегда пользуйтесь круглыми скобками при вызове функций, за исключением множественных случаев (распространенные идиомы в Lua):

• функции *.cfg{ } (box.cfg/memcached.cfg/..)
• функция ffi.cdef[[ ]]

Avoid the following constructions:

• <func>“<name>“. Strongly avoid require“..“.
• function object:method() end. Use function object.method(self) end instead.
• Semicolons as table separators. Only use commas.
• Semicolons at the end of line. Use semicolons only to split multiple statements on one line.
• Unnecessary function creation (closures/..).

Avoid implicit casting to boolean in if conditions like if x then or if not x then. Such expressions will likely result in troubles with box.NULL. Instead of those conditions, use if x ~= nil then and if x == nil then.

Модули

Don’t start modules with license/authors/descriptions, you can write it in LICENSE/AUTHORS/README files. To write modules, use one of the two patterns (don’t use modules()):

local M = {}

function M.foo()
    ...
end

function M.bar()
    ...
end

return M

или

local function foo()
    ...
end

local function bar()
    ...
end

return {
    foo = foo,
    bar = bar,
}

Комментирование

Don’t forget to comment your Lua code. You shouldn’t comment Lua syntax (assume that the reader already knows the Lua language). Instead, tell about functions/variable names/etc.

Start a sentence with a capital letter and end with a period.

Многострочные комментарии: используйте соответствующие скобки (--[[ ]]--) вместо простых (--[[ ]]).

Public function comments:

--- Copy any table (shallow and deep version).
-- * deepcopy: copies all levels
-- * shallowcopy: copies only first level
-- Supports __copy metamethod for copying custom tables with metatables.
-- @function gsplit
-- @table         inp  original table
-- @shallow[opt]  sep  flag for shallow copy
-- @returns            table (copy)

Тестирование

Use the tap module for writing efficient tests. Example of a test file:

#!/usr/bin/env tarantool

local test = require('tap').test('table')
test:plan(31)

do
    -- Check basic table.copy (deepcopy).
    local example_table = {
        { 1, 2, 3 },
        { "help, I'm very nested", { { { } } } }
    }

    local copy_table = table.copy(example_table)

    test:is_deeply(
            example_table,
            copy_table,
            "checking, that deepcopy behaves ok"
    )
    test:isnt(
            example_table,
            copy_table,
            "checking, that tables are different"
    )
    test:isnt(
            example_table[1],
            copy_table[1],
            "checking, that tables are different"
    )
    test:isnt(
            example_table[2],
            copy_table[2],
            "checking, that tables are different"
    )
    test:isnt(
            example_table[2][2],
            copy_table[2][2],
            "checking, that tables are different"
    )
    test:isnt(
            example_table[2][2][1],
            copy_table[2][2][1],
            "checking, that tables are different"
    )
end

<...>

os.exit(test:check() and 0 or 1)

When you test your code, the output will be something like this:

TAP version 13
1..31
ok - checking, that deepcopy behaves ok
ok - checking, that tables are different
ok - checking, that tables are different
ok - checking, that tables are different
ok - checking, that tables are different
ok - checking, that tables are different
...

Error handling

Принимайте разнообразные значения и выдавайте строго определенные.

With error handling, this means that you must provide an error object as the second multi-return value in case of error. The error object can be a string, a Lua table, cdata, or userdata. In the latter three cases, it must have a __tostring metamethod defined.

В случае ошибки нулевое значение nil должно быть первым возвращаемым значением. В таком случае ошибку трудно игнорировать.

При проверке возвращаемых значений функции проверяйте сначала первый аргумент. Если это nil, ищите ошибку во втором аргументе:

local data, err = foo()
if data == nil then
    return nil, err
end
return bar(data)

Unless the performance of your code is paramount, try to avoid using more than two return values.

In rare cases, you may want to return nil as a legal return value. In this case, it’s OK to check for error first and then for return:

local data, err = foo()
if err == nil then
    return data
end
return nil, err

luacheck

Для проверки стиля кода Tarantool использует luacheck. Он анализирует различные аспекты кода, например неиспользуемые переменные, и иногда проверяет больше аспектов, чем нужно. Поэтому есть соглашение игнорировать некоторые предупреждения, которые выдает luacheck:

"212/self",   -- Неиспользуемый аргумент <self>.
"411",        -- Переопределение локальной переменной.
"421",        -- Переопределение локальной переменной на вложенном уровне.
"431",        -- Переопределение значения, заданного ранее, в функции.
"432",        -- Перегрузка аргумента на вложенном уровне.