Software `/` code `/` prosody

Annotate

doc/coding_style.md @ 9858:54147de1d1b1

doc/coding_style.{txt,md}: Update coding style guide

author	Matthew Wild <mwild1@gmail.com>
date	Thu, 14 Mar 2019 16:13:14 +0000
child	9898:34a670e2bcfd

rev	line source
9858 54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	1
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	2 # Prosody Coding Style Guide
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	3
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	4 This style guides lists the coding conventions used in the
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	5 [Prosody](https://prosody.im/) project. It is based heavily on the [style guide used by the LuaRocks project](https://github.com/luarocks/lua-style-guide).
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	6
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	7 ## Indentation and formatting
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	8
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	9 * Prosody code is indented with tabs at the start of the line, a single
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	10 tab per logical indent level:
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	11
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	12 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	13 for i, pkg in ipairs(packages) do
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	14 for name, version in pairs(pkg) do
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	15 if name == searched then
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	16 print(version)
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	17 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	18 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	19 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	20 ```
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	21
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	22 Tab width is configurable in editors, so never assume a particular width.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	23 Specically this means you should not mix tabs and spaces, or use tabs for
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	24 alignment of items at different indentation levels.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	25
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	26 * Use LF (Unix) line endings.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	27
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	28 ## Comments
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	29
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	30 * Comments are encouraged where necessary to explain non-obvious code.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	31
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	32 * In general comments should be used to explain 'why', not 'how'
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	33
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	34 ### Comment tags
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	35
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	36 A comment may be prefixed with one of the following tags:
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	37
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	38 * FIXME: Indicates a serious problem with the code that should be addressed
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	39 * TODO: Indicates an open task, feature request or code restructuring that
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	40 is primarily of interest to developers (otherwise it should be in the
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	41 issue tracker).
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	42 * COMPAT: Must be used on all code that is present only for backwards-compatibility,
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	43 and may be removed one day. For example code that is added to support old
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	44 or buggy third-party software or dependencies.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	45
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	46 Example:
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	47
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	48 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	49 -- TODO: implement method
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	50 local function something()
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	51 -- FIXME: check conditions
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	52 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	53
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	54 ```
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	55
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	56 ## Variable names
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	57
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	58 * Variable names with larger scope should be more descriptive than those with
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	59 smaller scope. One-letter variable names should be avoided except for very
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	60 small scopes (less than ten lines) or for iterators.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	61
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	62 * `i` should be used only as a counter variable in for loops (either numeric for
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	63 or `ipairs`).
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	64
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	65 * Prefer more descriptive names than `k` and `v` when iterating with `pairs`,
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	66 unless you are writing a function that operates on generic tables.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	67
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	68 * Use `_` for ignored variables (e.g. in for loops:)
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	69
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	70 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	71 for _, item in ipairs(items) do
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	72 do_something_with_item(item)
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	73 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	74 ```
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	75
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	76 * Generally all identifiers (variables and function names) should use `snake_case`,
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	77 i.e. lowercase words joined by `_`.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	78
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	79 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	80 -- bad
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	81 local OBJEcttsssss = {}
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	82 local thisIsMyObject = {}
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	83 local c = function()
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	84 -- ...stuff...
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	85 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	86
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	87 -- good
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	88 local this_is_my_object = {}
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	89
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	90 local function do_that_thing()
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	91 -- ...stuff...
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	92 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	93 ```
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	94
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	95 > Rationale: The standard library uses lowercase APIs, with `joinedlowercase`
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	96 names, but this does not scale too well for more complex APIs. `snake_case`
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	97 tends to look good enough and not too out-of-place along side the standard
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	98 APIs.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	99
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	100 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	101 for _, name in pairs(names) do
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	102 -- ...stuff...
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	103 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	104 ```
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	105
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	106 * Prefer using `is_` when naming boolean functions:
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	107
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	108 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	109 -- bad
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	110 local function evil(alignment)
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	111 return alignment < 100
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	112 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	113
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	114 -- good
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	115 local function is_evil(alignment)
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	116 return alignment < 100
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	117 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	118 ```
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	119
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	120 * `UPPER_CASE` is to be used sparingly, with "constants" only.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	121
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	122 > Rationale: "Sparingly", since Lua does not have real constants. This
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	123 notation is most useful in libraries that bind C libraries, when bringing over
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	124 constants from C.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	125
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	126 * Do not use uppercase names starting with `_`, they are reserved by Lua.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	127
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	128 ## Tables
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	129
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	130 * When creating a table, prefer populating its fields all at once, if possible:
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	131
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	132 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	133 local player = { name = "Jack", class = "Rogue" }
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	134 }
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	135 ```
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	136
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	137 * Items should be separated by commas. If there are many items, put each
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	138 key/value on a separate line and use a semi-colon after each item (including
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	139 the last one):
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	140
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	141 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	142 local player = {
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	143 name = "Jack";
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	144 class = "Rogue";
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	145 }
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	146 ```
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	147
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	148 > Rationale: This makes the structure of your tables more evident at a glance.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	149 Trailing commas make it quicker to add new fields and produces shorter diffs.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	150
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	151 * Use plain `key` syntax whenever possible, use `["key"]` syntax when using names
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	152 that can't be represented as identifiers and avoid mixing representations in
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	153 a declaration:
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	154
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	155 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	156 local mytable = {
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	157 ["1394-E"] = val1,
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	158 ["UTF-8"] = val2,
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	159 ["and"] = val2,
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	160 }
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	161 ```
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	162
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	163 ## Strings
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	164
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	165 * Use `"double quotes"` for strings; use `'single quotes'` when writing strings
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	166 that contain double quotes.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	167
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	168 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	169 local name = "Prosody"
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	170 local sentence = 'The name of the program is "Prosody"'
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	171 ```
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	172
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	173 > Rationale: Double quotes are used as string delimiters in a larger number of
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	174 programming languages. Single quotes are useful for avoiding escaping when
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	175 using double quotes in literals.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	176
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	177 ## Line lengths
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	178
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	179 * There are no hard or soft limits on line lengths. Line lengths are naturally
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	180 limited by using one statement per line. If that still produces lines that are
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	181 too long (e.g. an expression that produces a line over 256-characters long,
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	182 for example), this means the expression is too complex and would do better
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	183 split into subexpressions with reasonable names.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	184
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	185 > Rationale: No one works on VT100 terminals anymore. If line lengths are a proxy
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	186 for code complexity, we should address code complexity instead of using line
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	187 breaks to fit mind-bending statements over multiple lines.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	188
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	189 ## Function declaration syntax
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	190
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	191 * Prefer function syntax over variable syntax. This helps differentiate between
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	192 named and anonymous functions.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	193
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	194 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	195 -- bad
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	196 local nope = function(name, options)
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	197 -- ...stuff...
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	198 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	199
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	200 -- good
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	201 local function yup(name, options)
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	202 -- ...stuff...
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	203 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	204 ```
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	205
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	206 * Perform validation early and return as early as possible.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	207
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	208 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	209 -- bad
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	210 local function is_good_name(name, options, arg)
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	211 local is_good = #name > 3
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	212 is_good = is_good and #name < 30
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	213
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	214 -- ...stuff...
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	215
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	216 return is_good
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	217 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	218
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	219 -- good
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	220 local function is_good_name(name, options, args)
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	221 if #name < 3 or #name > 30 then
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	222 return false
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	223 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	224
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	225 -- ...stuff...
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	226
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	227 return true
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	228 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	229 ```
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	230
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	231 ## Function calls
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	232
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	233 * Even though Lua allows it, generally you should not omit parentheses
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	234 for functions that take a unique string literal argument.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	235
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	236 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	237 -- bad
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	238 local data = get_data"KRP"..tostring(area_number)
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	239 -- good
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	240 local data = get_data("KRP"..tostring(area_number))
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	241 local data = get_data("KRP")..tostring(area_number)
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	242 ```
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	243
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	244 > Rationale: It is not obvious at a glace what the precedence rules are
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	245 when omitting the parentheses in a function call. Can you quickly tell which
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	246 of the two "good" examples in equivalent to the "bad" one? (It's the second
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	247 one).
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	248
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	249 * You should not omit parenthesis for functions that take a unique table
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	250 argument on a single line. You may do so for table arguments that span several
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	251 lines.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	252
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	253 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	254 local an_instance = a_module.new {
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	255 a_parameter = 42,
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	256 another_parameter = "yay",
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	257 }
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	258 ```
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	259
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	260 > Rationale: The use as in `a_module.new` above occurs alone in a statement,
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	261 so there are no precedence issues.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	262
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	263 ## Table attributes
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	264
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	265 * Use dot notation when accessing known properties.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	266
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	267 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	268 local luke = {
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	269 jedi = true,
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	270 age = 28,
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	271 }
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	272
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	273 -- bad
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	274 local is_jedi = luke["jedi"]
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	275
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	276 -- good
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	277 local is_jedi = luke.jedi
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	278 ```
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	279
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	280 * Use subscript notation `[]` when accessing properties with a variable or if using a table as a list.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	281
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	282 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	283 local vehicles = load_vehicles_from_disk("vehicles.dat")
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	284
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	285 if vehicles["Porsche"] then
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	286 porsche_handler(vehicles["Porsche"])
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	287 vehicles["Porsche"] = nil
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	288 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	289 for name, cars in pairs(vehicles) do
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	290 regular_handler(cars)
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	291 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	292 ```
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	293
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	294 > Rationale: Using dot notation makes it clearer that the given key is meant
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	295 to be used as a record/object field.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	296
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	297 ## Functions in tables
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	298
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	299 * When declaring modules and classes, declare functions external to the table definition:
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	300
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	301 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	302 local my_module = {}
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	303
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	304 function my_module.a_function(x)
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	305 -- code
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	306 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	307 ```
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	308
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	309 * When declaring metatables, declare function internal to the table definition.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	310
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	311 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	312 local version_mt = {
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	313 __eq = function(a, b)
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	314 -- code
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	315 end;
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	316 __lt = function(a, b)
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	317 -- code
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	318 end;
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	319 }
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	320 ```
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	321
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	322 > Rationale: Metatables contain special behavior that affect the tables
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	323 they're assigned (and are used implicitly at the call site), so it's good to
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	324 be able to get a view of the complete behavior of the metatable at a glance.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	325
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	326 This is not as important for objects and modules, which usually have way more
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	327 code, and which don't fit in a single screen anyway, so nesting them inside
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	328 the table does not gain much: when scrolling a longer file, it is more evident
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	329 that `check_version` is a method of `Api` if it says `function Api:check_version()`
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	330 than if it says `check_version = function()` under some indentation level.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	331
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	332 ## Variable declaration
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	333
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	334 * Always use `local` to declare variables.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	335
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	336 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	337 -- bad
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	338 superpower = get_superpower()
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	339
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	340 -- good
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	341 local superpower = get_superpower()
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	342 ```
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	343
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	344 > Rationale: Not doing so will result in global variables to avoid polluting
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	345 the global namespace.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	346
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	347 ## Variable scope
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	348
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	349 * Assign variables with the smallest possible scope.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	350
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	351 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	352 -- bad
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	353 local function good()
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	354 local name = get_name()
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	355
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	356 test()
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	357 print("doing stuff..")
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	358
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	359 --...other stuff...
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	360
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	361 if name == "test" then
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	362 return false
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	363 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	364
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	365 return name
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	366 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	367
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	368 -- good
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	369 local bad = function()
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	370 test()
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	371 print("doing stuff..")
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	372
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	373 --...other stuff...
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	374
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	375 local name = get_name()
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	376
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	377 if name == "test" then
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	378 return false
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	379 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	380
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	381 return name
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	382 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	383 ```
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	384
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	385 > Rationale: Lua has proper lexical scoping. Declaring the function later means that its
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	386 scope is smaller, so this makes it easier to check for the effects of a variable.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	387
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	388 ## Conditional expressions
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	389
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	390 * False and nil are falsy in conditional expressions. Use shortcuts when you
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	391 can, unless you need to know the difference between false and nil.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	392
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	393 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	394 -- bad
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	395 if name ~= nil then
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	396 -- ...stuff...
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	397 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	398
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	399 -- good
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	400 if name then
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	401 -- ...stuff...
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	402 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	403 ```
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	404
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	405 * Avoid designing APIs which depend on the difference between `nil` and `false`.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	406
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	407 * Use the `and`/`or` idiom for the pseudo-ternary operator when it results in
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	408 more straightforward code. When nesting expressions, use parentheses to make it
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	409 easier to scan visually:
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	410
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	411 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	412 local function default_name(name)
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	413 -- return the default "Waldo" if name is nil
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	414 return name or "Waldo"
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	415 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	416
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	417 local function brew_coffee(machine)
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	418 return (machine and machine.is_loaded) and "coffee brewing" or "fill your water"
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	419 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	420 ```
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	421
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	422 Note that the `x and y or z` as a substitute for `x ? y : z` does not work if
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	423 `y` may be `nil` or `false` so avoid it altogether for returning booleans or
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	424 values which may be nil.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	425
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	426 ## Blocks
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	427
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	428 * Use single-line blocks only for `then return`, `then break` and `function return` (a.k.a "lambda") constructs:
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	429
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	430 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	431 -- good
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	432 if test then break end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	433
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	434 -- good
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	435 if not ok then return nil, "this failed for this reason: " .. reason end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	436
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	437 -- good
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	438 use_callback(x, function(k) return k.last end)
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	439
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	440 -- good
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	441 if test then
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	442 return false
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	443 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	444
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	445 -- bad
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	446 if test < 1 and do_complicated_function(test) == false or seven == 8 and nine == 10 then do_other_complicated_function() end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	447
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	448 -- good
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	449 if test < 1 and do_complicated_function(test) == false or seven == 8 and nine == 10 then
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	450 do_other_complicated_function()
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	451 return false
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	452 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	453 ```
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	454
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	455 * Separate statements onto multiple lines. Do not use semicolons as statement terminators.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	456
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	457 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	458 -- bad
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	459 local whatever = "sure";
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	460 a = 1; b = 2
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	461
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	462 -- good
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	463 local whatever = "sure"
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	464 a = 1
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	465 b = 2
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	466 ```
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	467
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	468 ## Spacing
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	469
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	470 * Use a space after `--`.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	471
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	472 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	473 --bad
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	474 -- good
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	475 ```
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	476
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	477 * Always put a space after commas and between operators and assignment signs:
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	478
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	479 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	480 -- bad
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	481 local x = y*9
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	482 local numbers={1,2,3}
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	483 numbers={1 , 2 , 3}
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	484 numbers={1 ,2 ,3}
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	485 local strings = { "hello"
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	486 , "Lua"
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	487 , "world"
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	488 }
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	489 dog.set( "attr",{
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	490 age="1 year",
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	491 breed="Bernese Mountain Dog"
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	492 })
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	493
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	494 -- good
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	495 local x = y * 9
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	496 local numbers = {1, 2, 3}
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	497 local strings = {
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	498 "hello";
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	499 "Lua";
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	500 "world";
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	501 }
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	502 dog.set("attr", {
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	503 age = "1 year",
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	504 breed = "Bernese Mountain Dog",
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	505 })
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	506 ```
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	507
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	508 * Indent tables and functions according to the start of the line, not the construct:
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	509
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	510 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	511 -- bad
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	512 local my_table = {
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	513 "hello",
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	514 "world",
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	515 }
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	516 using_a_callback(x, function(...)
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	517 print("hello")
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	518 end)
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	519
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	520 -- good
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	521 local my_table = {
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	522 "hello";
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	523 "world";
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	524 }
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	525 using_a_callback(x, function(...)
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	526 print("hello")
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	527 end)
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	528 ```
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	529
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	530 > Rationale: This keep indentation levels aligned at predictable places. You don't
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	531 need to realign the entire block if something in the first line changes (such as
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	532 replacing `x` with `xy` in the `using_a_callback` example above).
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	533
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	534 * The concatenation operator gets a pass for avoiding spaces:
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	535
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	536 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	537 -- okay
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	538 local message = "Hello, "..user.."! This is your day # "..day.." in our platform!"
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	539 ```
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	540
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	541 > Rationale: Being at the baseline, the dots already provide some visual spacing.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	542
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	543 * No spaces after the name of a function in a declaration or in its arguments:
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	544
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	545 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	546 -- bad
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	547 local function hello ( name, language )
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	548 -- code
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	549 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	550
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	551 -- good
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	552 local function hello(name, language)
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	553 -- code
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	554 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	555 ```
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	556
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	557 * Add blank lines between functions:
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	558
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	559 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	560 -- bad
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	561 local function foo()
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	562 -- code
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	563 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	564 local function bar()
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	565 -- code
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	566 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	567
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	568 -- good
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	569 local function foo()
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	570 -- code
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	571 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	572
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	573 local function bar()
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	574 -- code
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	575 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	576 ```
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	577
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	578 * Avoid aligning variable declarations:
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	579
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	580 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	581 -- bad
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	582 local a = 1
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	583 local long_identifier = 2
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	584
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	585 -- good
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	586 local a = 1
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	587 local long_identifier = 2
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	588 ```
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	589
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	590 > Rationale: This produces extra diffs which add noise to `git blame`.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	591
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	592 * Alignment is occasionally useful when logical correspondence is to be highlighted:
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	593
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	594 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	595 -- okay
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	596 sys_command(form, UI_FORM_UPDATE_NODE, "a", FORM_NODE_HIDDEN, false)
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	597 sys_command(form, UI_FORM_UPDATE_NODE, "sample", FORM_NODE_VISIBLE, false)
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	598 ```
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	599
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	600 ## Typing
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	601
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	602 * In non-performance critical code, it can be useful to add type-checking assertions
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	603 for function arguments:
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	604
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	605 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	606 function manif.load_manifest(repo_url, lua_version)
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	607 assert(type(repo_url) == "string")
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	608 assert(type(lua_version) == "string" or not lua_version)
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	609
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	610 -- ...
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	611 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	612 ```
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	613
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	614 * Use the standard functions for type conversion, avoid relying on coercion:
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	615
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	616 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	617 -- bad
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	618 local total_score = review_score .. ""
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	619
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	620 -- good
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	621 local total_score = tostring(review_score)
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	622 ```
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	623
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	624 ## Errors
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	625
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	626 * Functions that can fail for reasons that are expected (e.g. I/O) should
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	627 return `nil` and a (string) error message on error, possibly followed by other
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	628 return values such as an error code.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	629
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	630 * On errors such as API misuse, an error should be thrown, either with `error()`
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	631 or `assert()`.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	632
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	633 ## Modules
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	634
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	635 Follow [these guidelines](http://hisham.hm/2014/01/02/how-to-write-lua-modules-in-a-post-module-world/) for writing modules. In short:
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	636
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	637 * Always require a module into a local variable named after the last component of the module’s full name.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	638
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	639 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	640 local bar = require("foo.bar") -- requiring the module
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	641
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	642 bar.say("hello") -- using the module
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	643 ```
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	644
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	645 * Don’t rename modules arbitrarily:
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	646
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	647 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	648 -- bad
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	649 local skt = require("socket")
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	650 ```
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	651
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	652 > Rationale: Code is much harder to read if we have to keep going back to the top
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	653 to check how you chose to call a module.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	654
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	655 * Start a module by declaring its table using the same all-lowercase local
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	656 name that will be used to require it. You may use an LDoc comment to identify
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	657 the whole module path.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	658
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	659 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	660 --- @module foo.bar
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	661 local bar = {}
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	662 ```
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	663
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	664 * Try to use names that won't clash with your local variables. For instance, don't
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	665 name your module something like “size”.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	666
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	667 * Use `local function` to declare _local_ functions only: that is, functions
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	668 that won’t be accessible from outside the module.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	669
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	670 That is, `local function helper_foo()` means that `helper_foo` is really local.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	671
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	672 * Public functions are declared in the module table, with dot syntax:
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	673
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	674 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	675 function bar.say(greeting)
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	676 print(greeting)
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	677 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	678 ```
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	679
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	680 > Rationale: Visibility rules are made explicit through syntax.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	681
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	682 * Do not set any globals in your module and always return a table in the end.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	683
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	684 * If you would like your module to be used as a function, you may set the
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	685 `__call` metamethod on the module table instead.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	686
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	687 > Rationale: Modules should return tables in order to be amenable to have their
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	688 contents inspected via the Lua interactive interpreter or other tools.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	689
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	690 * Requiring a module should cause no side-effect other than loading other
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	691 modules and returning the module table.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	692
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	693 * A module should not have state. If a module needs configuration, turn
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	694 it into a factory. For example, do not make something like this:
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	695
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	696 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	697 -- bad
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	698 local mp = require "MessagePack"
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	699 mp.set_integer("unsigned")
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	700 ```
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	701
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	702 and do something like this instead:
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	703
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	704 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	705 -- good
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	706 local messagepack = require("messagepack")
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	707 local mpack = messagepack.new({integer = "unsigned"})
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	708 ```
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	709
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	710 * The invocation of require may omit parentheses around the module name:
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	711
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	712 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	713 local bla = require "bla"
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	714 ```
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	715
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	716 ## Metatables, classes and objects
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	717
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	718 If creating a new type of object that has a metatable and methods, the
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	719 metatable and methods table should be separate, and the metatable name
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	720 should end with `_mt`.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	721
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	722 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	723 local mytype_methods = {};
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	724 local mytype_mt = { __index = mytype_methods };
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	725
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	726 function mytype_methods:add_new_thing(thing)
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	727 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	728
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	729 local function new()
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	730 return setmetatable({}, mytype_mt);
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	731 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	732
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	733 return { new = new };
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	734 ```
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	735
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	736 * Use the method notation when invoking methods:
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	737
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	738 ```
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	739 -- bad
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	740 my_object.my_method(my_object)
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	741
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	742 -- good
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	743 my_object:my_method()
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	744 ```
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	745
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	746 > Rationale: This makes it explicit that the intent is to use the function as a method.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	747
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	748 * Do not rely on the `__gc` metamethod to release resources other than memory.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	749 If your object manage resources such as files, add a `close` method to their
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	750 APIs and do not auto-close via `__gc`. Auto-closing via `__gc` would entice
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	751 users of your module to not close resources as soon as possible. (Note that
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	752 the standard `io` library does not follow this recommendation, and users often
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	753 forget that not closing files immediately can lead to "too many open files"
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	754 errors when the program runs for a while.)
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	755
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	756 > Rationale: The garbage collector performs automatic memory management,
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	757 dealing with memory only. There is no guarantees as to when the garbage
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	758 collector will be invoked, and memory pressure does not correlate to pressure
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	759 on other resources.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	760
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	761 ## File structure
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	762
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	763 * Lua files should be named in all lowercase.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	764
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	765 * Tests should be in a top-level `spec` directory. Prosody uses
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	766 [Busted](http://olivinelabs.com/busted/) for testing.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	767
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	768 ## Static checking
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	769
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	770 All code should pass [luacheck](https://github.com/mpeterv/luacheck) using
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	771 the `.luacheckrc` provided in the Prosody repository, and using miminal
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	772 inline exceptions.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	773
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	774 * luacheck warnings of class 211, 212, 213 (unused variable, argument or loop
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	775 variable) may be ignored, if the unused variable was added explicitly: for
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	776 example, sometimes it is useful, for code understandability, to spell out what
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	777 the keys and values in a table are, even if you're only using one of them.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	778 Another example is a function that needs to follow a given signature for API
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	779 reasons (e.g. a callback that follows a given format) but doesn't use some of
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	780 its arguments; it's better to spell out in the argument what the API the
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	781 function implements is, instead of adding `_` variables.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	782
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	783 ```
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	784 local foo, bar = some_function() --luacheck: ignore 212/foo
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	785 print(bar)
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	786 ```
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	787
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	788 * luacheck warning 542 (empty if branch) can also be ignored, when a sequence
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	789 of `if`/`elseif`/`else` blocks implements a "switch/case"-style list of cases,
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	790 and one of the cases is meant to mean "pass". For example:
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	791
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	792 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	793 if warning >= 600 and warning <= 699 then
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	794 print("no whitespace warnings")
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	795 elseif warning == 542 then --luacheck: ignore 542
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	796 -- pass
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	797 else
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	798 print("got a warning: "..warning)
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	799 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	800 ```
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	801
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	802 > Rationale: This avoids writing negated conditions in the final fallback
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	803 case, and it's easy to add another case to the construct without having to
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	804 edit the fallback.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	805

prosody

54147de1d1b1

doc/coding_style.md

Software / code / prosody

Annotate

doc/coding_style.md @ 9858:54147de1d1b1

Software `/` code `/` prosody