View source for Help:Lua/Lua best practice/pl

<languages/>
{{draft}}
<span lang="en" dir="ltr" class="mw-content-ltr">As any [[w:best practice|best practice]], this '''Lua best practice''' is heavily influenced by any individual contributors impression of what should be good practice.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Use whatever you believe is important on your specific project, but do also know that these rules have been found to work!</span>

<span lang="en" dir="ltr" class="mw-content-ltr">The examples in the following are for [[w:Lua (programming language)|Lua]], but they should be easy to reformulate for [[w:JavaScript|JavaScript]], [[w:PHP|PHP]], and [[w:Python (programming language)|Python]].</span>
<span lang="en" dir="ltr" class="mw-content-ltr">The reason for giving examples for Lua is that modules for this language are used a lot, often by non-programmers that do not see the consequence of their choices.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">As a general advice it can be a great help to import the code into a proper programming environment and check it there for obvious flaws and errors.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Several free options exist, among them [[w:Eclipse (software)|Eclipse]], [[w:TextMate|TextMate]], and [[w:Visual Studio Code|Visual Studio Code]] just to mention a few.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">Especially, use a lint tool like lualint or luacheck.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">The later is somewhat better.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Check also if there are tools for mess detection or other analysis available for your programming environment.</span><ref>
[http://lua-users.org/wiki/LuaLint LuaUsers: LuaLint]</ref><ref>[https://github.com/mpeterv/luacheck GitHub: mpeterv/luacheck]
</ref>

<span lang="en" dir="ltr" class="mw-content-ltr">Remember; consistent style is more important than the "right" style – even if that style is the one you prefer!</span><ref>
''The Art of Readable Code'' p. 21,34,43.
</ref>

<div lang="en" dir="ltr" class="mw-content-ltr">
==Names==
</div>

;{{anchor|descriptive-names}}<span lang="en" dir="ltr" class="mw-content-ltr">Descriptive names</span>
:<span lang="en" dir="ltr" class="mw-content-ltr">Chose descriptive names, avoid overly generic names like <code>get()</code> unless your code is truly generic. Don't repeat a description on several levels, like a method name set to the same as a class name, unless the method in fact return a class of that type. Think ''colorful'' words, more descriptive for larger scopes, but throw away unneeded words.</span><ref>''The Art of Readable Code'' pp. 8-11, Choose Specific Words.</ref>
;{{anchor|short-names}}<span lang="en" dir="ltr" class="mw-content-ltr">Short names</span>
:<span lang="en" dir="ltr" class="mw-content-ltr">Cryptic short names should be avoided. Spell out the names, but stay concise. Don't use <code>tmp_t</code>, say instead <code>temporaryTable</code> or <code>temporary_table</code>. Often you can reformulate the short names and still keep them short, like <code>entities</code> and <code>categories</code>. Use a plural name for tables holding several values for example.</span><ref>''The Art of Readable Code'' pp. 18-19, How Long Should a Name Be?</ref>
;{{anchor|iterator-names}}<span lang="en" dir="ltr" class="mw-content-ltr">Iterator names</span>
:<span lang="en" dir="ltr" class="mw-content-ltr">Iterators usually have short names in Lua, and the names carry special meaning. This goes against [[#short-names|short names]] and can create problems if several nested loops shall use the same names. A common solution is to prefix or suffix an additional part to the name, usually from the plural form used by the collection, or to use a singular form of the name of the collection.</span><ref>''The Art of Readable Code'' p. 12, Loop iterators.</ref>
;{{anchor|names-with-types}}<span lang="en" dir="ltr" class="mw-content-ltr">Names with types</span>
:<span lang="en" dir="ltr" class="mw-content-ltr">Lua has a rather weak type system, even if it looks like it is strong on some parts. Arguments should either be coerced to the correct type, or the function should throw an error. If the function exists in special incarnations to handle different types, then that should be part of the function name.</span><ref>''The Art of Readable Code'' pp. 15-17, Attaching Extra Information to a Name.</ref>
;{{anchor|acronyms-as-names}}<span lang="en" dir="ltr" class="mw-content-ltr">Acronyms as names</span>
:<span lang="en" dir="ltr" class="mw-content-ltr">Acronyms are intimidating for those that does not know their meaning. Do not use them unless it the simplest and most obvious cases. In a library for creating HTML markup <code>td()</code> might be acceptable, but in a library for creating infoboxes the same may not be acceptable.</span><ref>''The Art of Readable Code'' pp. 19-20, Acronyms and Abbreviations.</ref>
;{{anchor|format-names}}<span lang="en" dir="ltr" class="mw-content-ltr">Format names</span>
:<span lang="en" dir="ltr" class="mw-content-ltr">Formatting of names should follow the convention on the actual project. Lua as such uses several formatting styles, but in Wikimedia projects it seems to be [[w:Camel case|UpperCamelCase]] for class names, and lowerCamelCase for function, method and variable names. Module names seem to be interpreted as variable names. There are no clear practice for constants, but [[w:Snake case|UPPER_CASE_EMBEDDED_UNDERSCORE]] seems like a wise bet.</span><ref>''The Art of Readable Code'' pp. 20-21, Use Name Formatting to Convey Meaning.</ref>
;{{anchor|single-underscore}}<span lang="en" dir="ltr" class="mw-content-ltr">Single underscore</span>
:<span lang="en" dir="ltr" class="mw-content-ltr">In Lua code a single underscore name is used wherever a name must be provided, but it is not used. That is it is a ''placeholder'' that is otherwise ignored. This is recognized by some lint tools, and should also be respected in ordinary code.</span><ref>[http://lua-users.org/wiki/LuaStyleGuide LuaUsers:LuaStyleGuide]</ref><ref>[https://www.lua.org/pil/1.3.html Programming in Lua: 1.3 – Some Lexical Conventions]</ref>
;{{anchor|leading-underscore}}<span lang="en" dir="ltr" class="mw-content-ltr">Leading underscore</span>
:<span lang="en" dir="ltr" class="mw-content-ltr">By convention a leading underscore is used for names that are somewhat private but of some reason must be placed so it is accessible from the outside. Variables with such names should be treated as private to whatever defined them, unless they have some very clear explanation that say you can do some specific operations on them.</span><ref>[http://lua-users.org/wiki/LuaStyleGuide LuaUsers:LuaStyleGuide]</ref><ref>[https://www.lua.org/pil/1.3.html Programming in Lua: 1.3 – Some Lexical Conventions]</ref>

<div lang="en" dir="ltr" class="mw-content-ltr">
==Formatting==
</div>

;{{anchor|limit-line-length}}<span lang="en" dir="ltr" class="mw-content-ltr">Limit line length</span>
:<span lang="en" dir="ltr" class="mw-content-ltr">Lines should be limited to a reasonable length, typically around 80 characters. The reason is that long lines are hard to read, and as they grow longer they tend to contain more intermingled concepts, and editing them will tend to create new bugs.</span><ref>[https://www.python.org/dev/peps/pep-0008/#maximum-line-length PEP-8: Maximum Line Length] (This style guide use 79 chars.)</ref>
;{{anchor|indentation-of-newlines}}<span lang="en" dir="ltr" class="mw-content-ltr">Indentation of newlines</span>
:<span lang="en" dir="ltr" class="mw-content-ltr">Programmers have opinions on how to do indentation of newlines. Whatever opinion you have, do remember that crowdsourced projects should adhere to some common standards. Note that while a ''tab'' looks like the same as 4 spaces in the online editor, it does not show up like this in the normal view. Because the online editor do indentation in specific ways you should set your programming environment to act the same way.</span><ref>[https://www.python.org/dev/peps/pep-0008/#indentation PEP-8: Indentation]</ref><ref>[https://www.python.org/dev/peps/pep-0008/#tabs-or-spaces PEP-8: Tabs or spaces]</ref>
;{{anchor|binaries-and-linebreaks}}<span lang="en" dir="ltr" class="mw-content-ltr">Binaries and line breaks</span>
:<span lang="en" dir="ltr" class="mw-content-ltr">Sometimes it is necessary to put a line break inside an expression, typically an if-clause. This pose a special problem, as it opens up for copy-paste induced errors. To avoid problems a simple formatting tricks can be used, simply put the logical binary operator in front of the expression on a new line.</span><ref>[https://www.python.org/dev/peps/pep-0008/#should-a-line-break-before-or-after-a-binary-operator PEP-8: Should a line break before or after a binary operator?]</ref>
:{| class="wikitable mw-collapsible mw-collapsed"
!colspan="2"|Example&nbsp;
|-
!Good
!Bad
|- valign="top"
|<syntaxhighlight lang="lua">
if long_statement_A
    and long_statement_B
    and long_statement_C
then
    …
</syntaxhighlight>
|<syntaxhighlight lang="lua">
if long_statement_A and
    long_statement_B and
    long_statement_C then
    …
</syntaxhighlight>
|}
;{{anchor|whitespace}}<span lang="en" dir="ltr" class="mw-content-ltr">Whitespace</span>
:<span lang="en" dir="ltr" class="mw-content-ltr">Whitespace is usually a GoodThing™, but people tend to disagree on how to use it. Done ''right'' it tends to increase readability of your code, but done ''wrong'' your code can be really hard to read. Find a style guide and stick to it. Or use a tool.</span><ref>[https://www.python.org/dev/peps/pep-0008/#whitespace-in-expressions-and-statements PEP-8: Whitespace in Expressions and Statements]</ref>

<div lang="en" dir="ltr" class="mw-content-ltr">
==Documentation==
</div>

;{{anchor|interface-documentation}}<span lang="en" dir="ltr" class="mw-content-ltr">Interface documentation</span>
:<span lang="en" dir="ltr" class="mw-content-ltr">The interface is the exposed functions from the module, that is the functions you can invoke from the parser function. As a minimum document whatever arguments the interface function takes, and whatever value it returns. The parser function will only use a single returned value, no matter what the function returns. Remember to document if and how the metafunction <code>__tostring</code> will transform the return value.</span>
;{{anchor|overview-documentation}}<span lang="en" dir="ltr" class="mw-content-ltr">Overview documentation</span>
:<span lang="en" dir="ltr" class="mw-content-ltr">The documentation should have an overview to give a general explanation of why and how the module, function, or variable is the way it is. This is not just the intended behaviour, it is why the behaviour is the way it is.</span>
;{{anchor|parameter-annotation}}<span lang="en" dir="ltr" class="mw-content-ltr">Parameter annotation</span>
:<span lang="en" dir="ltr" class="mw-content-ltr">Each parameter should be properly annotated. That is the expected type should be given and a short descriptive string. Write as if LDoc or a similar tool was available, usually as <code>-- @param ''type'' ''optional string''</code>.</span>
;{{anchor|return-annotation}}<span lang="en" dir="ltr" class="mw-content-ltr">Return annotation</span>
:<span lang="en" dir="ltr" class="mw-content-ltr">Each return value should be properly annotated. That is the expected type should be given and a short descriptive string. Write as if LDoc or a similar tool was available, usually as <code>-- @return ''type'' ''optional string''</code>.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
==Comments==
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Inline comments for the code itself.
</div>

;{{anchor|why-comments}}<span lang="en" dir="ltr" class="mw-content-ltr">Why-form of comments</span>
:<span lang="en" dir="ltr" class="mw-content-ltr">Comments are not only for you as the person who coded the program, they are also for those who read your code. In the code path there should be answers to the how-questions, and in the comments there should be answers to the why-questions. Do not fall in the trap of replicating what you do in the code path in the comments, good comments provide new insight into the code.</span><ref>''The Art of Readable Code'' p. 56. The box has an alternate approach to what-why-how.</ref>
;{{anchor|state-your-intent}}<span lang="en" dir="ltr" class="mw-content-ltr">State your intent</span>
:<span lang="en" dir="ltr" class="mw-content-ltr">State the intent of your code, in a clear and precise language. Do not just add a lot of words, think about the reader, what do they need to know to understand your code.</span><ref>''The Art of Readable Code'' pp. 62-63, State the Intent of Your Code.</ref>
;{{anchor|refactor-on-comments}}<span lang="en" dir="ltr" class="mw-content-ltr">Refactor on comments</span>
:<span lang="en" dir="ltr" class="mw-content-ltr">When the code has become complex, it is common to start explaining the code in order to help yourself. If you need your own comments, then something has gotten too involved and you should [[w:refactor|refactor]] the code.</span><ref>[https://refactoring.guru/smells/comments Refactoring Guru: CodeSmells: Disposables: Comments]</ref>
;{{anchor|comments-on-bad-names}}<span lang="en" dir="ltr" class="mw-content-ltr">Comments on bad names</span>
:<span lang="en" dir="ltr" class="mw-content-ltr">A comment saying that a name is bad in some respect does not help. Do not comment on bad names, fix them!</span><ref>''The Art of Readable Code'' p. 49, Don’t Comment Bad Names—Fix the Names Instead.</ref>
;{{anchor|todo-comments}}<span lang="en" dir="ltr" class="mw-content-ltr">"Todo" comments</span>
:<span lang="en" dir="ltr" class="mw-content-ltr">The marker ''todo'' is one of several common ones, and can be interpreted as "code the main programmer has not gotten around to fix yet". Usually you should write it as <code>-- @todo ''optional string''</code>.</span><ref>''The Art of Readable Code'' p. 50, Comment the Flaws in Your Code.</ref>
;{{anchor|fixme-comments}}<span lang="en" dir="ltr" class="mw-content-ltr">"Fixme" comments</span>
:<span lang="en" dir="ltr" class="mw-content-ltr">The marker ''fixme'' is one of several common ones, and can be interpreted as "code someone other than main programmer has identified as broken". Usually you should write it as <code>-- @fixme ''optional string''</code>. This is an invitation to others to try to fix the code.</span><ref>''The Art of Readable Code'' p. 50, Comment the Flaws in Your Code.</ref>
;{{anchor|hack-comments}}<span lang="en" dir="ltr" class="mw-content-ltr">"Hack" comments</span>
:<span lang="en" dir="ltr" class="mw-content-ltr">The marker ''hack'' is one of several common ones, and can be interpreted as "code someone other than main programmer has identified as broken and tried fixing in an unelegant way". Usually you should write it as <code>-- @hack ''optional string''</code>. This is an invitation to others to try to fix the code.</span><ref>''The Art of Readable Code'' p. 50, Comment the Flaws in Your Code.</ref>
;{{anchor|xxx-comments}}<span lang="en" dir="ltr" class="mw-content-ltr">"XXX" comments</span>
:<span lang="en" dir="ltr" class="mw-content-ltr">The marker ''xxx'' is one of several common ones, and can be interpreted as "code identified as dangerously broken". Usually you should write it as <code>-- @xxx ''optional string''</code>. This marker should not be in production code, the code should be fixed asap.</span><ref>''The Art of Readable Code'' p. 50, Comment the Flaws in Your Code.</ref>
;{{anchor|comments-on-magic-numbers}}<span lang="en" dir="ltr" class="mw-content-ltr">Comments on magic numbers</span>
:<span lang="en" dir="ltr" class="mw-content-ltr">Constants and other magic numbers should have comments explaining why they have the specific content. Why is the line length set to 80 chars? Why is π truncated to 3.14?</span><ref>''The Art of Readable Code'' p. 51, Comment on Your Constants.</ref>


<div lang="en" dir="ltr" class="mw-content-ltr">
==Code==
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Small patterns and coding practices.
</div>

;{{anchor|patterns}}<span lang="en" dir="ltr" class="mw-content-ltr">Software patterns</span>
:<span lang="en" dir="ltr" class="mw-content-ltr">A lot of work has gone into identifying common [[w:Software design pattern|software design patterns]], and developing good general solutions to those patterns.</span> <span lang="en" dir="ltr" class="mw-content-ltr">If you suspect you are attempting to do something that has a common pattern then do a search and check out how to implement the pattern.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Still, know that patterns for languages ''with'' [[w:closure (computer programming)|closures]] can be very different from those ''without'' closures. Usually tables are used in Lua to create objects, but they can also be created as closures.</span><ref>''JavaScript Patterns''. p. 2</ref><ref>[https://www.lua.org/pil/6.1.html Programming in Lua: 6.1 – Closures]</ref><ref>[http://lua-users.org/wiki/MinimisingClosures LuaUsers: Minimising Closures]</ref>
;{{anchor|string-quotes}}<span lang="en" dir="ltr" class="mw-content-ltr">String quotes</span>
:<span lang="en" dir="ltr" class="mw-content-ltr">In Lua there are several types of string quotes. Pick one of them and stick with it. If you need several types of quotes, either use your typical quote at the outermost level or at the innermost, and work your way out. Inside out with single quote as the primary quote and double quotes as secondary seems to be common, but could simply be accidental. If more quotes are necessary, then start using double square brackets at the ternary level.</span><ref>[https://www.python.org/dev/peps/pep-0008/#string-quotes PEP-8: String Quotes]</ref><ref>[http://lua-users.org/wiki/StringsTutorial LuaUsers: StringsTutorial]</ref>
;{{anchor|return-early}}<span lang="en" dir="ltr" class="mw-content-ltr">Return early</span>
:<span lang="en" dir="ltr" class="mw-content-ltr">Return as soon as possible, especially if something fails. Usually programmers are told to stick with a single return point, but due to the language constructs in Lua this seems to create deeply nested code. It is thus better to return early.</span><ref>''The Art of Readable Code'' pp. 75-79, Returning Early from a Function.</ref>
:{| class="wikitable mw-collapsible mw-collapsed"
!colspan="2"|Example&nbsp;
|-
!Good
!Bad
|- valign="top"
|<syntaxhighlight lang="lua">
…
if done then
    return done
end
…
</syntaxhighlight>
|<syntaxhighlight lang="lua">
…
if not done then
    …
end
…
return done
</syntaxhighlight>
|}
;{{anchor|truthy-first}}<span lang="en" dir="ltr" class="mw-content-ltr">Truthy expressions first</span>
:<span lang="en" dir="ltr" class="mw-content-ltr">Usually you are free to order clauses in ''then'' and ''else'' as you see fit, and you should order the clauses so the if-clause has a positive test. This makes the code easier to read. If you can avoid the else-clause that is although more important.</span><ref>''The Art of Readable Code'' pp. 70-73, The Order of Arguments in Conditionals.</ref>
:{| class="wikitable mw-collapsible mw-collapsed"
!colspan="2"|Example&nbsp;
|-
!Good
!Bad
|- valign="top"
|<syntaxhighlight lang="lua">
if a == b then
    …
else
    …
end
</syntaxhighlight>
|<syntaxhighlight lang="lua">
if a ~= b then
    …
else
    …
end
</syntaxhighlight>
|}
;{{anchor|interrogated-first}}<span lang="en" dir="ltr" class="mw-content-ltr">Interrogated first</span>
:<span lang="en" dir="ltr" class="mw-content-ltr">Usually the interrogated value goes first in a logical expression, as this is more natural to read and thus less error prone. The inverted form is sometimes called the ''Yoda form''. Sometimes (but rarely) the natural form does not work as expected, and the code terminates. This can be because Lua fails figure out a proper tail recursive form of the expression, and then the stack overflows.</span><ref>''The Art of Readable Code'' pp. 70-73, The Order of Arguments in Conditionals.</ref>
:{| class="wikitable mw-collapsible mw-collapsed"
!colspan="2"|Example&nbsp;
|-
!Good
!Bad
|- valign="top"
|<syntaxhighlight lang="lua">
if length > 10 then
    …
</syntaxhighlight>
|<syntaxhighlight lang="lua">
if 10 <= length then
    …
</syntaxhighlight>
|}
;{{anchor|provide-defaults}}<span lang="en" dir="ltr" class="mw-content-ltr">Provide defaults</span>
:<span lang="en" dir="ltr" class="mw-content-ltr">In languages with an <code>or</code> operator like in Lua, it is very easy to provide defaults. This is nice as some common constructs fails badly if given an uninitialized value. This happen for example when a table is uninitialized and the code tries to index the nil value.</span><ref>[https://www.lua.org/pil/3.3.html Programming in Lua: 3.3 – Logical Operators]</ref>
:{| class="wikitable mw-collapsible mw-collapsed"
!colspan="2"|Example&nbsp;
|-
!Good
!Bad
|- valign="top"
|<syntaxhighlight lang="lua">
…
local t = arg or {}
…
t['foo']
</syntaxhighlight>
|<syntaxhighlight lang="lua">
…
local t = arg
…
if t then
    t['foo']
else
    …
end
</syntaxhighlight>
|}
;{{anchor|binary-conditional}}<span lang="en" dir="ltr" class="mw-content-ltr">Binary conditional</span>
:<span lang="en" dir="ltr" class="mw-content-ltr">Lua does not have a binary conditional operator (??), or “nullish coalescing operator”, but you can do the same with an <code>or</code> operator. What goes on is although a little mysterious to newcomers to Lua. The logical operators <code>and</code> and <code>or</code> pass on truthy values (materialized values), and thus they can be part of other expressions than just logical ones.</span><ref>[http://lua-users.org/wiki/TernaryOperator LuaUsers: TernaryOperator] (This is for ternary conditional, but the binary conditional is pretty similar.)</ref>
:{| class="wikitable mw-collapsible mw-collapsed"
!colspan="2"|Example&nbsp;
|-
!Good
!Bad
|- valign="top"
|<syntaxhighlight lang="lua">
local area = (length or 0) * (width or 0)
</syntaxhighlight>
|<syntaxhighlight lang="lua">
local area = 0
if length and width then
    area = length * width
end
</syntaxhighlight>
|}
;{{anchor|ternary-conditional}}<span lang="en" dir="ltr" class="mw-content-ltr">Ternary conditional</span>
:<span lang="en" dir="ltr" class="mw-content-ltr">Lua does not have a ternary conditional operator (?:), but you can do the same with an <code>and</code> and an <code>or</code> operator. What goes on is although a little mysterious to newcomers to Lua. The logical operators <code>and</code> and <code>or</code> pass on truthy values (materialized values), and thus they can be part of other expressions than just logical ones.</span><ref>[http://lua-users.org/wiki/TernaryOperator LuaUsers: TernaryOperator]</ref>
:{| class="wikitable mw-collapsible mw-collapsed"
!colspan="2"|Example&nbsp;
|-
!Good
!Bad
|- valign="top"
|<syntaxhighlight lang="lua">
local height = pressure and millibarToMeters(length) or 0
</syntaxhighlight>
|<syntaxhighlight lang="lua">
local height = 0
if pressure then
    height = millibarToMeters(pressure)
end
</syntaxhighlight>
|}
:<span lang="en" dir="ltr" class="mw-content-ltr">Note that the form <code>''a'' and ''b'' or ''c''</code> where ''b'' is falsy will give ''c'' as outcome. That may not be the expected behavior.</span> 
;{{anchor|avoid-repeat-until}}<span lang="en" dir="ltr" class="mw-content-ltr">Avoid repeat…until</span>
:<span lang="en" dir="ltr" class="mw-content-ltr">The loop construct <code>repeat…until</code> delays the test until after the loop. This is error prone and should be avoided. The only times this is acceptable is when the test itself is costly compared to the executed block, or avoiding the repeat-clause would imply additional cleanup or finalize code.</span><ref>''The Art of Readable Code'' pp. 74-75, Avoid do/while Loops.</ref>
;{{anchor|test-arguments}}<span lang="en" dir="ltr" class="mw-content-ltr">Test arguments</span>
:<span lang="en" dir="ltr" class="mw-content-ltr">There is a small utility {{ll|Extension:Scribunto/Lua reference manual#libraryUtil|libraryUtil}} to test arguments types, and it should be used to avoid simple mistakes.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Often the arguments are valid when other code is correct, but in fringe cases something creates a call outside the expected type range and the code fails in mysterious ways.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Proper testing might catch an error early, and increase the probability of discovering the real root cause.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Still note that type testing is a test for ''failure'', and not a test for ''correctness''.</span>
:{| class="wikitable mw-collapsible mw-collapsed"
!colspan="2"|Example&nbsp;
|-
!Good
!Bad
|- valign="top"
|<syntaxhighlight lang="lua">
local util = require 'libraryUtil'
local checkType = util.checkType

function concat( a, b )
    checkType( 'foo', 1, a, 'string' )
    checkType( 'foo', 1, b, 'number' )
    return a..'='..tostring(b)
end
</syntaxhighlight>
|<syntaxhighlight lang="lua">
function foo( a, b )
    return a..'='..tostring(b)
end
</syntaxhighlight>
|}


<div lang="en" dir="ltr" class="mw-content-ltr">
==Patterns==
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
A few very common [[w:software pattern|software patterns]].
</div>

;{{anchor|comman-pattern}}<span lang="en" dir="ltr" class="mw-content-ltr">Command pattern</span>
:<span lang="en" dir="ltr" class="mw-content-ltr">The single most common software pattern in Lua modules, that is most commonly missing, is the [[w:Command pattern|command pattern]]. Some data is available, and some action should be chosen given this data. A typical ''smell'' that a command pattern is missing is long chains of if-then-elseif-end tests. The most common variant does not have named commands, but an accept-qualifier function. Both versions are very common in parsing arguments from the "invoke" parser function.</span>
:{| class="wikitable mw-collapsible mw-collapsed"
!colspan="2"|Example&nbsp;
|-
|<syntaxhighlight lang="lua">
local commands = {}
-- each member of the command table is a simplified "ConcreteCommand"
commands['foo'] = function( val ) return -math.sqrt(-val) end
commands['bar'] = function( val ) return 0 end
commands['baz'] = function( val ) return math.sqrt(val) end

function sqrt( command, value ) -- execute for the "Command"
    return commands[command]( value ) -- execute for the "ConcreteCommand"
end

sqrt( -4 ) --> -2 (Should really be a complex number!)
</syntaxhighlight>
|-
|<syntaxhighlight lang="lua">
local commands = {}
-- each member of the command table is a simplified "ConcreteCommand"
table.insert( commands, { function( val ) return value < 0 end, function( val ) return -math.sqrt(-val) end } )
table.insert( commands, { function( val ) return value == 0 end, function( val ) return 0 end } )
table.insert( commands, { function( val ) return value > 0 end, function( val ) return math.sqrt(val) end } )

function sumSqrt( value ) -- execute for the "Command"
    local accumulator = 0
    for _,command in ipairs( commands ) do
        command[1]( value ) then -- accept for the "ConcreteCommand"
            accumulator = accumulator + command[2]( value ) -- execute for the "ConcreteCommand"
        end
    end

end

sumSqrt( -4 ) --> -2 (Should really be a complex number!)
</syntaxhighlight>
|}

<div lang="en" dir="ltr" class="mw-content-ltr">
==Testability==
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">About testing and how to make the code testable.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Note that the original book from ''the gang of four'' has software patterns for strongly typed languages, which does not fit a weakly typed language very well.</span><ref>
''JavaScript Patterns''. p. 2
</ref>
<span lang="en" dir="ltr" class="mw-content-ltr">Whether Lua is strongly typed, or weakly, is up for debate.</span><ref>
[http://the4thwiki.com/lua/types.html Lua for Python Programmers: Types]
</ref>

;{{anchor|complexity}}<span lang="en" dir="ltr" class="mw-content-ltr">Complexity</span>
:<span lang="en" dir="ltr" class="mw-content-ltr">There are usually several execute paths through a given code, and this makes the code difficult to understand. The more code paths the more difficult the code become. This can be measured as [[w:cyclomatic complexity|cyclomatic complexity]], and is a count of paths by counting branch points. This gives a fair, but not very good measure on code quality.</span><ref>[https://quandarypeak.com/2015/02/measuring-software-maintainability/ Quandary Peak Research: Measuring Software Maintainability]</ref>
;{{anchor|avoid-globals}}<span lang="en" dir="ltr" class="mw-content-ltr">Avoid globals</span>
:<span lang="en" dir="ltr" class="mw-content-ltr">Functions with globals are hard to test, no matter how the globals are included in the code. To avoid this accidental trap libraries can be included to wet the module, like <code>require('[[w:Module:No globals|Module:No globals]]')</code>. Still note that ''requiring'' some code is like importing a global, so be careful not to create a bigger problem.</span> <ref>[http://wiki.c2.com/?GlobalVariablesAreBad C2Wiki: Global Variables Are Bad]</ref><ref>[https://playcontrol.net/ewing/jibberjabber/using-closures-in-lua-to-av.html PlayControl Software: Using closures in Lua to avoid global variables for callbacks]</ref><ref>''JavaScript Patterns'', pp. 12-13</ref>
:{| class="wikitable mw-collapsible mw-collapsed"
!colspan="2"|Example&nbsp;
|-
!Good
!Bad
|- valign="top"
|<syntaxhighlight lang="lua">
local t = {}
function f( arg, opts )
    do_something( arg, opts )
end
f( 'somevalue', t )
</syntaxhighlight>
|<syntaxhighlight lang="lua">
local t = {}
function f( arg )
    do_something( arg, t )
end
f( 'somevalue' )
</syntaxhighlight>
|}
;{{anchor|avoid-changing-scope}}<span lang="en" dir="ltr" class="mw-content-ltr">Avoid changing scope</span>
:<span lang="en" dir="ltr" class="mw-content-ltr">In Lua it is possible to check the scope of a function. Don't do that, as the function will then depend on "mini-globals", which is nearly as bad as globals. If everything works as it should, then the mini-globals are probably semi-constant, but there are no such guarantee.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
==Security==
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Lua runs in a kind of sandboxed environment, you may say that the Lua code executes in a dmz on the outside of the usual server, where only a few calls pass through the wall and those should be properly validated by the internal code. In general there should be no reason to take any special precautions to make the code secure, as the result from the code execution will pass through proper cleaning and escaping before being included on the page.
</div>

<span id="See_also"></span>
== Zobacz też ==

* {{ll|Extension:Scribunto/Lua reference manual|2=<span lang="en" dir="ltr" class="mw-content-ltr">Lua reference manual</span>}}

<div lang="en" dir="ltr" class="mw-content-ltr">
==Programming environment==
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Some advices for how to set up your external programming environment.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
===Visual Studio Code===
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Use something like the following extensions.
</div>

* [https://marketplace.visualstudio.com/items?itemName=keyring.Lua Lua]
* [https://marketplace.visualstudio.com/items?itemName=dwenegar.vscode-luacheck vscode-luacheck]
*: <span lang="en" dir="ltr" class="mw-content-ltr">This needs a file <code>.luacheckrc</code> with a single line <code>globals = { 'mw' }</code>, otherwise it will complain a lot about the <code>mw</code> global variable.</span>
* [https://marketplace.visualstudio.com/items?itemName=jeblad-3.WMFsnippets Lua snippets for Wikimedia]

<div lang="en" dir="ltr" class="mw-content-ltr">
===Other tools===
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
This is tools you might find useful.
</div>
* [https://github.com/LuaDist/luametrics GitHub: LuaDist/luametrics]

<div lang="en" dir="ltr" class="mw-content-ltr">
==References==
</div>
<references/>

<div lang="en" dir="ltr" class="mw-content-ltr">
==Reading==
</div>

* Kerievsky, Joshua; ''Refactoring to Patterns''
* Boswell, Dustin; Foucher, Trevor; ''The Art of Readable Code''
* Stefanov, Stoyan; ''JavaScript Patterns''
* Gamma, Erich; Helm, Richard; Johnson, Ralph; Vlissides, John; ''Design Patterns: Elements of Reusable Object-Oriented Software''
* ''[https://www.lua.org/pil/contents.html Programming in Lua (5.0)]''
* ''[https://www.lua.org/manual/5.1/ Lua 5.1 Reference Manual]''
* ''[http://lua-users.org/wiki/SampleCode LuaUsers: Sample Code]''
* ''[https://www.python.org/dev/peps/pep-0008/ PEP 8 -- Style Guide for Python Code]''
* ''[http://lua-users.org/wiki/LuaStyleGuide LuaUsers: Lua Style Guide]''
* ''[http://pixelscommander.com/wp-content/uploads/2014/12/P10.pdf The Power of Ten – Rules for Developing Safety Critical Code]''