User:Ganaram inukshuk/Provisional style guide for Lua

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

Parts of it are adapted for use on the wiki, with details on specific conventions. If a specific convention is missing, fall back to that described in the Luarocks style guide.

Preliminaries

Indentation and formatting

The in-browser Lua editor uses tabs for indenting, which equates to 4 spaces.

Declaring and naming variables

Variable names should be short and descriptive, written snake_case. Exceptions to this include counter variables, like with i in for loops. Boolean variables are prefixed with is_. Constants are named using TRAIN_CASE.

All variable declarations should start with local.

Strings

Strings are enclosed in double quotes " ". If a string contains double quotes, do not escape them while enclosing the string in double quotes, as this reduces readability; instead, enclose the string in single quotes ' '. Escape characters are only necessary if the string contains both single and double quotes.

Preferred

local sentence = "That's his cheese quesadilla!"
local quotation = "And he said to me, \"One man's trash is another man's treasure.\""

Avoid

local formatting = "padding: 0.25em 0.5em; border: 1px solid white;\" colspan="2\" | "

Line lengths

The 80-column limit is to be obeyed wherever possible for both comments and code, except for cases where strings, inline comments, or function calls are too long.

	local function navbox_title()
		if not title then return "" end
		local has_navbar = name ~= nil

		return "|-\n" ..
			'! style="text-align: center; background-color: #eaecf0; white-space: nowrap; margin: 0em 4em 0em 4em;' ..
			'padding: 0.25em 0.5em; border: 1px solid white;" colspan="2" | ' ..
			'<span style="display: inline-block; float: left; text-align: left; font-weight: normal; font-style: normal; min-width: 4em; padding: 0px; margin: 0px;">' ..
			(has_navbar and navbar(name, "mini", "") or "") .. '</span>' ..
			'<span style="font-size: 1.05em;">' .. title .. '</span>' ..
			(is_collapsible and '' or '<span style="display: inline-block; float: right; font-size: 0.8em; width: 5em;">&nbsp;</span>')
	end

Naming, declaring, and calling functions

As with variables, functions are named using snake_case.

tbd

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.