prosody
5669bb11ac7b
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 @ 9888:5669bb11ac7b

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