prosody
7ca5645f46cd
doc/coding_style.md

Find changesets by keywords by author, files, the commit message, revision number or hash, or revset expression.

Software / code / prosody

Annotate

doc/coding_style.md @ 12658:7ca5645f46cd

usermanager: Remove concept of global authz provider Rationale: - Removes a bunch of code! - We don't have many cases where an actor is not bound to one of our hosts - A notable exception is the admin shell, but if we ever attempt to lock those sessions down, there is a load of other work that also has to be done. And it's not clear if we would need a global authz provider for that anyway. - Removes an extra edge case from the necessary mental model for operators - Sessions that aren't bound to a host generally are anonymous or have an alternative auth model (such as by IP addres). - With the encapsulation now provided by util.roles, ad-hoc "detached roles" can still be created anyway by code that needs them.
author Matthew Wild <mwild1@gmail.com>
date Fri, 12 Aug 2022 16:21:57 +0100
parent 12387:05c250fa335a
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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