User:Ganaram inukshuk/Provisional style guide for Lua

Parts of it are adapted to follow editing on the wiki.

Lua style

The following style guide is a provisional guide adapted from the LuaRocks style guide: https://github.com/luarocks/lua-style-guide

Indentation and formatting

Use the default as specified by the in-browser Lua editor.

Documentation

to be determined

Variable names

Same as LuaRocks style guide.

Tables

Same as LuaRocks style guide.

Strings

Same as LuaRocks style guide.

Do not escape double-quotes when a string can be enclosed in single-quotes instead. Only escape double-quotes when a string contains both single and double quotes.

Line lengths

to be determined

Function declaration syntax

Same as LuaRocks style guide

Function calls

Same as LuaRocks style guide.

Use of wrapper functions

Allowed.

Table attributes

to be determined

Blocks

to be determined

Spacing

Use a space after --, used for comments. The lack of a space after -- should indicate commented-out code.

Comments in code

Well-commented code should speak for itself. Self-documenting code can only go so far, so comments should be used to briefly describe what the function does. If a module has several types of functions, comments can also be used as section separators.

TODOs are allowed in comments. Separating TODOs into the module's documentation page makes code harder to maintain.

Commented-out code

Only block comments --[[ ]]-- should only be used for commented-out code. This can be hard to do if a string contains a ]], so -- may be used instead.

Specific conventions

Boilerplate code

Alphabetize dependencies, except for p, which goes last and separated by a line. Equals signs may be lined up. Placement of comments to be determined.

Preferred order

local mos     = require("Module:MOS")
local rat     = require("Module:Rational")
local utils   = require("Module:Utils")
local et      = require("Module:ET")
local tip     = require("Module:Template input parse")
local tamnams = require("Module:TAMNAMS")
local yesno   = require("Module:Yesno")

local p = {}

Avoid

local mos = require("Module:MOS")
local rat = require("Module:Rational")
local utils = require("Module:Utils")
local et = require("Module:ET")
local tip = require("Module:Template input parse")
local tamnams = require("Module:TAMNAMS")
local yesno = require("Module:Yesno")
local p = {}

Mediawiki table formatting

Wikitables should be written with one line per cell instead of one line per row. This is for ease-of-reading when debugging the output of a module-generated table. Add a space between pipes/exclamation points and table entries to avoid accidentally adding new rows, such as when inputting negative numbers. Mediawiki tables generated using Lua code must follow this convention.

Preferred

{| class="wikitable"
|+ Caption text
|-
! Header 1
! Header 2
! Header 3
|-
| aa
| bb
| cc
|-
| dd
| ee
| ff
|}

Avoid

{| class="wikitable"
|+ Caption text
|-
! Header 1 !! Header 2 !! Header 3
|-
| aa || bb || cc
|-
| dd || ee || ff
|}

Lua code that generates a table

Experimental; yet to be fully adopted

Brought up when trying to make example code; turns out, this is recommended practice for large tables: https://www.lua.org/pil/11.6.html

    table.insert(lines, '{| class="wikitable"')
    table.insert(lines, '|+ Caption text')
    table.insert(lines, '|-')
    table.insert(lines, '! Header 1')
    table.insert(lines, '! Header 2')
    table.insert(lines, '! Header 3')
    table.insert(lines, '|-')
    table.insert(lines, '| aa')
    table.insert(lines, '| bb')
    table.insert(lines, '| cc')
    table.insert(lines, '|-')
    table.insert(lines, '| dd')
    table.insert(lines, '| ee')
    table.insert(lines, '| ff')
    table.insert(lines, '|}')
    
    return table.concat(lines, '\n')

Use of nested functions

Recommended for functions whose helper functions only serve that function, but may be disregarded for testing. Nested functions have access to the variables and parameters of the outer function, so an equivalent nested function may require fewer parameters.

function some_function(args)
    -- Get args here
    local arg1 = args["Arg 1"]
    local arg2 = args["Arg 2"]
    
    -- Helper function
    function helper_function(some_value)

    end
end

Use of wrapper functions

Recommended, but may be disregarded for simple modules. The use of a wrapper and "main" function allows for a module to be used directly in another module or indirectly through its corresponding template. This also allows for code testing by calling the "main" function, or through a tester function.

-- "Main" function to be called by wrapper or another module
function p._call_me(args)
    
end

-- Function to be called by template
function p._call_me(frame)
    local args = getArgs(frame)
    
    return p._call_me(args)
end

-- Tester function; test wrapper that calls the "main" function
function p.tester()
    local args = {}
    return p._call_me(args)
end

Templates and modules

Param names

Capitalized, short, and descriptive parameter names are preferred wherever possible, such as Scale Signature, and not scalesig or ssg. Non-capitalized parameter names are used for debugging, testing, or meta-use (parameters used to build other templates and typically would never be seen in normal use), such as name and debug.