Annotate

doc/coding_style.md @ 11763:e273ef869794

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