User:Ganaram inukshuk/Provisional style guide for Lua: Difference between revisions
Undo (some) unauthorized changes (this wasn't meant to be edited by others); updated with guides on TODO and comments |
|||
| (4 intermediate revisions by 2 users 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 | ||
|- | |||
! Header 1 | ! Header 1 | ||
! Header 2 | ! Header 2 | ||
| Line 63: | Line 72: | ||
| ee | | ee | ||
| ff | | ff | ||
|} | |}</nowiki> | ||
}} | |||
</pre> | </pre> | ||
''' | '''Avoid''' | ||
<pre<includeonly />> | |||
<pre> | {{avoid|<nowiki>{| class="wikitable" | ||
{| class="wikitable" | |+ Caption text | ||
|+ | |- | ||
! Header 1 !! Header 2 !! Header 3 | ! Header 1 !! Header 2 !! Header 3 | ||
|- | |- | ||
|aa ||bb ||cc | | aa || bb || cc | ||
|- | |- | ||
|dd ||ee ||ff | | dd || ee || ff | ||
|} | |}</nowiki> | ||
}} | |||
</pre> | </pre> | ||
== Templates and modules == | |||
=== Param names === | |||
Capitalized, short, and descriptive parameter names are preferred wherever possible, such as <code>Scale Signature</code>, and not <code>scalesig</code> or <code>ssg</code>. Non-capitalized parameter names can be used for testing or debugging purposes, such as <code>debug</code> and <code>nocat</code>. | |||