User:Ganaram inukshuk/Provisional style guide for Lua: Difference between revisions
ArrowHead294 (talk | contribs) |
Undo (some) unauthorized changes (this wasn't meant to be edited by others); updated with guides on TODO and comments |
||
| (2 intermediate revisions by one other user not shown) | |||
| Line 40: | Line 40: | ||
=== Spacing === | === Spacing === | ||
Use a space after <code>--</code>, used for comments. The lack of a space after <code>--</code> should indicate commented-out code. | 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 === | ||
Only block comments <code> --[[ ]]-- </code> should only be used for commented-out 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 <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. | |||
== Mediawiki table formatting == | == 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. | |||
''' | '''Preferred''' | ||
<pre> | <pre<includeonly />> | ||
{| class="wikitable" | {{preferred|<nowiki>{| class="wikitable" | ||
|+ Caption text | |+ Caption text | ||
|- | |- | ||
| Line 64: | Line 72: | ||
| ee | | ee | ||
| ff | | ff | ||
|} | |}</nowiki> | ||
}} | |||
</pre> | </pre> | ||
'''Avoid | '''Avoid''' | ||
<pre> | <pre<includeonly />> | ||
{| class="wikitable" | {{avoid|<nowiki>{| class="wikitable" | ||
|+ Caption text | |+ Caption text | ||
|- | |- | ||
| Line 77: | Line 86: | ||
|- | |- | ||
| dd || ee || ff | | dd || ee || ff | ||
|} | |}</nowiki> | ||
}} | |||
</pre> | </pre> | ||
Latest revision as of 19:27, 12 March 2025
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.
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.
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
|}
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.