Software `/` code `/` prosody

Annotate

doc/coding_style.md @ 13103:42c2a9787242

net.http.server: Remove "Firing event" logs, use event logging instead Since these are noisy and we have the thing in util.helpers to log events fired. The new status line events are meant to replace these as they include more useful info.

author	Kim Alvefur <zash@zash.se>
date	Sun, 14 May 2023 18:48:20 +0200
parent	12387:05c250fa335a

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
9939 3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	16 print(version);
9858 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.
12387 05c250fa335a Spelling: Fix various spelling mistakes (thanks timeless) Kim Alvefur <zash@zash.se> parents: 11727 diff changeset	23 Specifically this means you should not mix tabs and spaces, or use tabs for
9858 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
9939 3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	72 do_something_with_item(item);
9858 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
9939 3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	88 local this_is_my_object = {};
9858 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)
9939 3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	116 return alignment < 100;
9858 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
9939 3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	133 local player = { name = "Jack", class = "Rogue" };
9858 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 * 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	137 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	138 the last one):
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	139
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	140 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	141 local player = {
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	142 name = "Jack";
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	143 class = "Rogue";
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	144 }
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 > Rationale: This makes the structure of your tables more evident at a glance.
9939 3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	148 Trailing semi-colons make it quicker to add new fields and produces shorter diffs.
9858 54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	149
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	150 * 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	151 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	152 a declaration:
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	153
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	154 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	155 local mytable = {
9939 3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	156 ["1394-E"] = val1;
3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	157 ["UTF-8"] = val2;
3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	158 ["and"] = val2;
9858 54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	159 }
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 ## Strings
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	163
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	164 * 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	165 that contain double quotes.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	166
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	167 ```lua
9939 3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	168 local name = "Prosody";
3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	169 local sentence = 'The name of the program is "Prosody"';
9858 54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	170 ```
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 > 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	173 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	174 using double quotes in literals.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	175
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	176 ## Line lengths
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	177
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	178 * 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	179 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	180 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	181 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	182 split into subexpressions with reasonable names.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	183
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	184 > 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	185 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	186 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	187
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	188 ## Function declaration syntax
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	189
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	190 * 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	191 named and anonymous functions.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	192
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	193 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	194 -- bad
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	195 local nope = function(name, options)
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	196 -- ...stuff...
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	197 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	198
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	199 -- good
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	200 local function yup(name, options)
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	201 -- ...stuff...
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	202 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	203 ```
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 * 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	206
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	207 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	208 -- bad
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	209 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	210 local is_good = #name > 3
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	211 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	212
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	213 -- ...stuff...
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	214
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	215 return is_good
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	216 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	217
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	218 -- good
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	219 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	220 if #name < 3 or #name > 30 then
9939 3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	221 return false;
9858 54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	222 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	223
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	224 -- ...stuff...
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	225
9939 3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	226 return true;
9858 54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	227 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	228 ```
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 ## Function calls
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	231
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	232 * 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	233 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	234
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	235 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	236 -- bad
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	237 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	238 -- good
9939 3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	239 local data = get_data("KRP"..tostring(area_number));
3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	240 local data = get_data("KRP")..tostring(area_number);
9858 54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	241 ```
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 > 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	244 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	245 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	246 one).
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	247
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	248 * 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	249 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	250 lines.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	251
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	252 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	253 local an_instance = a_module.new {
9939 3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	254 a_parameter = 42;
3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	255 another_parameter = "yay";
9858 54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	256 }
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 > 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	260 so there are no precedence issues.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	261
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	262 ## Table attributes
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	263
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	264 * 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	265
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	266 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	267 local luke = {
9939 3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	268 jedi = true;
3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	269 age = 28;
9858 54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	270 }
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 -- bad
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	273 local is_jedi = luke["jedi"]
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	274
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	275 -- good
9939 3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	276 local is_jedi = luke.jedi;
9858 54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	277 ```
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 * 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	280
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	281 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	282 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	283
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	284 if vehicles["Porsche"] then
9939 3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	285 porsche_handler(vehicles["Porsche"]);
3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	286 vehicles["Porsche"] = nil;
9858 54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	287 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	288 for name, cars in pairs(vehicles) do
9939 3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	289 regular_handler(cars);
9858 54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	290 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	291 ```
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 > 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	294 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	295
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	296 ## Functions in tables
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	297
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	298 * 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	299
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	300 ```lua
9939 3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	301 local my_module = {};
9858 54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	302
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	303 function my_module.a_function(x)
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	304 -- code
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	305 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	306 ```
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 * 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	309
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	310 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	311 local version_mt = {
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	312 __eq = function(a, b)
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	313 -- code
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	314 end;
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	315 __lt = function(a, b)
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	316 -- code
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	317 end;
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	318 }
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 > 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	322 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	323 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	324
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	325 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	326 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	327 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	328 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	329 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	330
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	331 ## Variable declaration
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	332
9899 8c831c76fc94 doc/coding_style: Trim trailing whitespace Kim Alvefur <zash@zash.se> parents: 9898 diff changeset	333 * Always use `local` to declare variables.
9858 54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	334
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	335 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	336 -- bad
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	337 superpower = get_superpower()
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	338
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	339 -- good
9939 3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	340 local superpower = get_superpower();
9858 54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	341 ```
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 > 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	344 the global namespace.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	345
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	346 ## Variable scope
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	347
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	348 * 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	349
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	350 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	351 -- bad
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	352 local function good()
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	353 local name = get_name()
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	354
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	355 test()
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	356 print("doing stuff..")
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	357
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	358 --...other stuff...
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	359
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	360 if name == "test" then
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	361 return false
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	362 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	363
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	364 return name
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	365 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	366
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	367 -- good
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	368 local bad = function()
9939 3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	369 test();
3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	370 print("doing stuff..");
9858 54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	371
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	372 --...other stuff...
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	373
9939 3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	374 local name = get_name();
9858 54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	375
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	376 if name == "test" then
9939 3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	377 return false;
9858 54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	378 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	379
9939 3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	380 return name;
9858 54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	381 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	382 ```
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 > 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	385 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	386
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	387 ## Conditional expressions
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	388
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	389 * 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	390 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	391
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	392 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	393 -- bad
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	394 if name ~= nil then
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	395 -- ...stuff...
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	396 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	397
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	398 -- good
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	399 if name then
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	400 -- ...stuff...
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	401 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	402 ```
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 * 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	405
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	406 * 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	407 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	408 easier to scan visually:
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	409
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	410 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	411 local function default_name(name)
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	412 -- return the default "Waldo" if name is nil
9939 3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	413 return name or "Waldo";
9858 54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	414 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	415
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	416 local function brew_coffee(machine)
9939 3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	417 return (machine and machine.is_loaded) and "coffee brewing" or "fill your water";
9858 54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	418 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	419 ```
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 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	422 `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	423 values which may be nil.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	424
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	425 ## Blocks
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	426
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	427 * 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	428
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	429 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	430 -- good
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	431 if test then break end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	432
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	433 -- good
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	434 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	435
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	436 -- good
9939 3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	437 use_callback(x, function(k) return k.last end);
9858 54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	438
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	439 -- good
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	440 if test then
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	441 return false
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	442 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	443
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	444 -- bad
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	445 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	446
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	447 -- good
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	448 if test < 1 and do_complicated_function(test) == false or seven == 8 and nine == 10 then
9939 3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	449 do_other_complicated_function();
3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	450 return false;
9858 54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	451 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	452 ```
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	453
9900 f2104b36f673 doc/coding_style: The codebase uses semicolons Kim Alvefur <zash@zash.se> parents: 9899 diff changeset	454 * Separate statements onto multiple lines. Use semicolons as statement terminators.
9858 54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	455
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	456 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	457 -- bad
9900 f2104b36f673 doc/coding_style: The codebase uses semicolons Kim Alvefur <zash@zash.se> parents: 9899 diff changeset	458 local whatever = "sure"
f2104b36f673 doc/coding_style: The codebase uses semicolons Kim Alvefur <zash@zash.se> parents: 9899 diff changeset	459 a = 1 b = 2
9858 54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	460
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	461 -- good
9900 f2104b36f673 doc/coding_style: The codebase uses semicolons Kim Alvefur <zash@zash.se> parents: 9899 diff changeset	462 local whatever = "sure";
f2104b36f673 doc/coding_style: The codebase uses semicolons Kim Alvefur <zash@zash.se> parents: 9899 diff changeset	463 a = 1;
f2104b36f673 doc/coding_style: The codebase uses semicolons Kim Alvefur <zash@zash.se> parents: 9899 diff changeset	464 b = 2;
9858 54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	465 ```
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 ## Spacing
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	468
9899 8c831c76fc94 doc/coding_style: Trim trailing whitespace Kim Alvefur <zash@zash.se> parents: 9898 diff changeset	469 * Use a space after `--`.
9858 54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	470
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	471 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	472 --bad
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	473 -- good
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	474 ```
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 * 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	477
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	478 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	479 -- bad
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	480 local x = y*9
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	481 local numbers={1,2,3}
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	482 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 local strings = { "hello"
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	485 , "Lua"
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	486 , "world"
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	487 }
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	488 dog.set( "attr",{
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	489 age="1 year",
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	490 breed="Bernese Mountain Dog"
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	491 })
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 -- good
9939 3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	494 local x = y * 9;
3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	495 local numbers = {1, 2, 3};
9858 54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	496 local strings = {
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	497 "hello";
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	498 "Lua";
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	499 "world";
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	500 }
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	501 dog.set("attr", {
9939 3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	502 age = "1 year";
3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	503 breed = "Bernese Mountain Dog";
3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	504 });
9858 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 * 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	508
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	509 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	510 -- bad
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	511 local my_table = {
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	512 "hello",
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	513 "world",
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	514 }
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	515 using_a_callback(x, function(...)
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	516 print("hello")
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	517 end)
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	518
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	519 -- good
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	520 local my_table = {
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	521 "hello";
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	522 "world";
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	523 }
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	524 using_a_callback(x, function(...)
9939 3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	525 print("hello");
9858 54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	526 end)
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	527 ```
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 > 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	530 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	531 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	532
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	533 * 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	534
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	535 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	536 -- okay
9939 3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	537 local message = "Hello, "..user.."! This is your day # "..day.." in our platform!";
9858 54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	538 ```
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 > 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	541
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	542 * 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	543
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	544 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	545 -- bad
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	546 local function hello ( name, language )
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	547 -- code
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	548 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	549
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	550 -- good
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	551 local function hello(name, language)
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	552 -- code
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	553 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	554 ```
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 * Add blank lines between functions:
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	557
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	558 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	559 -- bad
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	560 local function foo()
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	561 -- code
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	562 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	563 local function bar()
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	564 -- code
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	565 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	566
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	567 -- good
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	568 local function foo()
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	569 -- code
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	570 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	571
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	572 local function bar()
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	573 -- code
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	574 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	575 ```
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 * Avoid aligning variable declarations:
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	578
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	579 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	580 -- bad
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	581 local a = 1
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	582 local long_identifier = 2
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	583
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	584 -- good
9939 3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	585 local a = 1;
3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	586 local long_identifier = 2;
9858 54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	587 ```
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	588
11000 d9aae4734f38 coding_style: Replace mention of git with hg Kim Alvefur <zash@zash.se> parents: 9939 diff changeset	589 > Rationale: This produces extra diffs which add noise to `hg annotate`.
9858 54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	590
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	591 * 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	592
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	593 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	594 -- okay
9939 3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	595 sys_command(form, UI_FORM_UPDATE_NODE, "a", FORM_NODE_HIDDEN, false);
3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	596 sys_command(form, UI_FORM_UPDATE_NODE, "sample", FORM_NODE_VISIBLE, false);
9858 54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	597 ```
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 ## Typing
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	600
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	601 * 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	602 for function arguments:
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	603
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	604 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	605 function manif.load_manifest(repo_url, lua_version)
9939 3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	606 assert(type(repo_url) == "string");
3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	607 assert(type(lua_version) == "string" or not lua_version);
9858 54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	608
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 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	611 ```
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 * 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	614
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	615 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	616 -- bad
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	617 local total_score = review_score .. ""
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	618
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	619 -- good
9939 3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	620 local total_score = tostring(review_score);
9858 54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	621 ```
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 ## Errors
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	624
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	625 * 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	626 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	627 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	628
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	629 * 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	630 or `assert()`.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	631
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	632 ## Modules
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	633
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	634 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	635
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	636 * 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	637
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	638 ```lua
9939 3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	639 local bar = require("foo.bar"); -- requiring the module
9858 54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	640
9939 3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	641 bar.say("hello"); -- using the module
9858 54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	642 ```
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 * Don’t rename modules arbitrarily:
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	645
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	646 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	647 -- bad
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	648 local skt = require("socket")
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	649 ```
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 > 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	652 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	653
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	654 * 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	655 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	656 the whole module path.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	657
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	658 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	659 --- @module foo.bar
9939 3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	660 local bar = {};
9858 54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	661 ```
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 * 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	664 name your module something like “size”.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	665
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	666 * 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	667 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	668
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	669 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	670
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	671 * 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	672
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	673 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	674 function bar.say(greeting)
9939 3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	675 print(greeting);
9858 54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	676 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	677 ```
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 > 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	680
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	681 * 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	682
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	683 * 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	684 `__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	685
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	686 > 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	687 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	688
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	689 * 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	690 modules and returning the module table.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	691
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	692 * 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	693 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	694
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	695 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	696 -- bad
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	697 local mp = require "MessagePack"
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	698 mp.set_integer("unsigned")
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	699 ```
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 and do something like this instead:
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	702
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	703 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	704 -- good
9939 3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	705 local messagepack = require("messagepack");
3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	706 local mpack = messagepack.new({integer = "unsigned"});
9858 54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	707 ```
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 * 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	710
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	711 ```lua
9939 3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	712 local bla = require "bla";
9858 54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	713 ```
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 ## Metatables, classes and objects
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	716
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	717 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	718 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	719 should end with `_mt`.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	720
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	721 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	722 local mytype_methods = {};
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	723 local mytype_mt = { __index = mytype_methods };
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	724
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	725 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	726 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	727
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	728 local function new()
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	729 return setmetatable({}, mytype_mt);
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	730 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	731
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	732 return { new = new };
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	733 ```
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 * 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	736
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 -- bad
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	739 my_object.my_method(my_object)
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	740
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	741 -- good
9939 3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	742 my_object:my_method();
9858 54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	743 ```
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 > 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	746
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	747 * 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	748 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	749 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	750 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	751 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	752 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	753 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	754
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	755 > 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	756 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	757 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	758 on other resources.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	759
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	760 ## File structure
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	761
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	762 * 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	763
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	764 * 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	765 [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	766
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	767 ## Static checking
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	768
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	769 All code should pass [luacheck](https://github.com/mpeterv/luacheck) using
11727 f3aee8a825cc Fix various spelling errors (thanks codespell) Kim Alvefur <zash@zash.se> parents: 11000 diff changeset	770 the `.luacheckrc` provided in the Prosody repository, and using minimal
9858 54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	771 inline exceptions.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	772
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	773 * 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	774 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	775 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	776 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	777 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	778 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	779 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	780 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	781
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	782 ```
9939 3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	783 local foo, bar = some_function(); --luacheck: ignore 212/foo
3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	784 print(bar);
9858 54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	785 ```
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 * 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	788 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	789 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	790
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	791 ```lua
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	792 if warning >= 600 and warning <= 699 then
9939 3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	793 print("no whitespace warnings");
9858 54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	794 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	795 -- pass
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	796 else
9939 3a7f822f6edd doc/coding_style: apply consistent semi-colon usage marc0s <marcos@tenak.net> parents: 9900 diff changeset	797 print("got a warning: "..warning);
9858 54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	798 end
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	799 ```
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 > 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	802 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	803 edit the fallback.
54147de1d1b1 doc/coding_style.{txt,md}: Update coding style guide Matthew Wild <mwild1@gmail.com> parents: diff changeset	804

prosody

42c2a9787242

doc/coding_style.md

Software / code / prosody

Annotate

doc/coding_style.md @ 13103:42c2a9787242

Software `/` code `/` prosody