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

← Older edit

VisualWikitext

@@ Line 40: / Line 40: @@
 === 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 ===
-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 ==
-Unless the cells in the table contain short content and no custom styling, 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.
+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.
-'''Use this'''
+'''Preferred'''
 <pre<includeonly />>
 {{preferred|<nowiki>{| class="wikitable"
@@ Line 68: / Line 76: @@
 </pre>
-'''Avoid this'''
+'''Avoid'''
 <pre<includeonly />>
 {{avoid|<nowiki>{| class="wikitable"