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

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

Avoid

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

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 can be used for testing or debugging purposes, such as debug and nocat.