Xenharmonic Wiki

User:Ganaram inukshuk/Provisional style guide for Lua: Difference between revisions

← Older editNewer edit →
VisualWikitext
Ganaram inukshuk (talk | contribs)
autopatrolled, emailconfirmed
6,211 edits
No edit summary
Ganaram inukshuk (talk | contribs)
autopatrolled, emailconfirmed
6,211 edits
No edit summary
Line 8: Line 8:
The in-browser Lua editor uses tabs for indenting, which equates to 4 spaces.
The in-browser Lua editor uses tabs for indenting, which equates to 4 spaces.


=== Declaring and naming variables ===
=== Naming and declaring variables ===


Variable names should be short and descriptive, written <code>snake_case</code>. Exceptions to this include counter variables, like with <code>i</code> in for loops. Boolean variables are prefixed with <code>is_</code>. Constants are named using <code>TRAIN_CASE</code>.
Variable names should be short and descriptive, written <code>snake_case</code>. Exceptions to this include counter variables, like with <code>i</code> in for loops. Boolean variables are prefixed with <code>is_</code>. Constants are named using <code>TRAIN_CASE</code>.
Line 29: Line 29:
=== Line lengths ===
=== 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.
The 80-column limit is to be observed wherever possible for both comments and code, except for cases where strings, inline comments, or function calls are too long.


<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
Line 51: Line 51:


''tbd''
''tbd''
=== Table attributes ===
''to be determined''
=== Blocks ===
''to be determined''
=== Spacing ===
Use a space after <code>--</code>, used for comments. The lack of a space after <code>--</code> should indicate commented-out code.


=== Comments in code ===
=== Comments in code ===
Line 72: Line 62:
Only block comments <code> --[[  ]]-- </code> should only be used for commented-out code. This can be hard to do if a string contains a <code>]]</code>, so <code>--</code> may be used instead.
Only block comments <code> --[[  ]]-- </code> should only be used for commented-out code. This can be hard to do if a string contains a <code>]]</code>, so <code>--</code> may be used instead.


== Specific conventions ==
== Conventions for lua modules ==


=== Boilerplate code ===
=== Boilerplate code ===
Line 97: Line 87:
local p = {}
local p = {}
</syntaxhighlight>
</syntaxhighlight>
=== Use of functions ===
===== "Main", wrapper, and tester functions =====
Templates should consist of at least two functions: a "main" function prefixed with an underscore, and a wrapper function without an underscore.
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 rule may be disregarded for simple modules, or modules whose use is to provide a single function for other modules.
For testing purposes, a tester function may be added, which is itself a wrapper that calls the main function.<syntaxhighlight lang="lua">
-- "Main" function to be called by wrapper or another module
function p._call_me(args)
    return "something" .. args["something"]
end
-- Function to be called by template
function p.call_me(frame)
    return p._call_me(frame.args)
end
-- Tester function; test wrapper that calls the "main" function
function p.tester()
    local args = { ["something"] = 123 }
    return p._call_me(args)
end
</syntaxhighlight>
==== Helper functions ====
For code readability, the use of helper functions is recommended.
Helper functions may be nested within the calling function if those helpers only serve that function. This rule may be disregarded for testing purposes. Nested functions have access to the variables and parameters of the outer function, so an equivalent nested function may require fewer parameters.<syntaxhighlight lang="lua">function some_function(args)
    -- Get args here
    local arg1 = args["Arg 1"]
    local arg2 = args["Arg 2"]
   
    -- Helper function
    function helper_function(some_value)
        return "result" .. some_value
    end
end</syntaxhighlight>


=== Mediawiki table formatting ===
=== Mediawiki table formatting ===
Line 128: Line 157:
</syntaxhighlight>
</syntaxhighlight>


=== Lua code that generates a table ===
=== Concatenating strings ===
'''Experimental; yet to be fully adopted'''
'''Experimental; yet to be fully adopted'''


Line 149: Line 178:
      
      
     return table.concat(lines, '\n')
     return table.concat(lines, '\n')
</syntaxhighlight>
=== 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.<syntaxhighlight lang="lua">
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
</syntaxhighlight>
=== 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.<syntaxhighlight lang="lua">
-- "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
</syntaxhighlight>
</syntaxhighlight>


Retrieved from "https://en.xen.wiki/w/User:Ganaram_inukshuk/Provisional_style_guide_for_Lua"