Software /
code /
prosody
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 |
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 |