Software `/` code `/` prosody

Annotate

doc/coding_style.md @ 12556:706375b75475

mod_mam: Silence luacheck (yay warnings in CI but not locally)

author	Kim Alvefur <zash@zash.se>
date	Tue, 14 Jun 2022 22:06:21 +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

706375b75475

doc/coding_style.md

Software / code / prosody

Annotate

doc/coding_style.md @ 12556:706375b75475

Software `/` code `/` prosody