prosody-hg: doc/coding_style.md comparison

comparison doc/coding_style.md @ 9939:3a7f822f6edd

doc/coding_style: apply consistent semi-colon usage Make all "good" statements in the coding style document use consistent statement-separator semi-colon

author	marc0s <marcos@tenak.net>
date	Sat, 30 Mar 2019 18:44:34 +0100
parents	f2104b36f673
children	d9aae4734f38

comparison

equal deleted inserted replaced

-:4e8ba156738b
+:3a7f822f6edd
 ```lua
 for i, pkg in ipairs(packages) do
 for name, version in pairs(pkg) do
 if name == searched then
-print(version)
+print(version);
 end
 end
 end
 ```
 * Use `_` for ignored variables (e.g. in for loops:)
 ```lua
 for _, item in ipairs(items) do
-do_something_with_item(item)
+do_something_with_item(item);
 end
 ```
 * Generally all identifiers (variables and function names) should use `snake_case`,
 i.e. lowercase words joined by `_`.
 local c = function()
 -- ...stuff...
 end
 -- good
-local this_is_my_object = {}
+local this_is_my_object = {};
 local function do_that_thing()
 -- ...stuff...
 end
 ```
 return alignment < 100
 end
 -- good
 local function is_evil(alignment)
-return alignment < 100
+return alignment < 100;
 end
 ```
 * `UPPER_CASE` is to be used sparingly, with "constants" only.
 ## Tables
 * When creating a table, prefer populating its fields all at once, if possible:
 ```lua
-local player = { name = "Jack", class = "Rogue" }
+local player = { name = "Jack", class = "Rogue" };
 ```
 * Items should be separated by commas. If there are many items, put each
 key/value on a separate line and use a semi-colon after each item (including
 the last one):
 class = "Rogue";
 }
 ```
 > **Rationale:** This makes the structure of your tables more evident at a glance.
-Trailing commas make it quicker to add new fields and produces shorter diffs.
+Trailing semi-colons make it quicker to add new fields and produces shorter diffs.
 * Use plain `key` syntax whenever possible, use `["key"]` syntax when using names
 that can't be represented as identifiers and avoid mixing representations in
 a declaration:
 ```lua
 local mytable = {
-["1394-E"] = val1,
+["1394-E"] = val1;
-["UTF-8"] = val2,
+["UTF-8"] = val2;
-["and"] = val2,
+["and"] = val2;
 }
 ```
 ## Strings
 * Use `"double quotes"` for strings; use `'single quotes'` when writing strings
 that contain double quotes.
 ```lua
-local name = "Prosody"
+local name = "Prosody";
-local sentence = 'The name of the program is "Prosody"'
+local sentence = 'The name of the program is "Prosody"';
 ```
 > **Rationale:** Double quotes are used as string delimiters in a larger number of
 programming languages. Single quotes are useful for avoiding escaping when
 using double quotes in literals.
 end
 -- good
 local function is_good_name(name, options, args)
 if #name < 3 or #name > 30 then
-return false
+return false;
 end
 -- ...stuff...
-return true
+return true;
 end
 ```
 ## Function calls
 ```lua
 -- bad
 local data = get_data"KRP"..tostring(area_number)
 -- good
-local data = get_data("KRP"..tostring(area_number))
+local data = get_data("KRP"..tostring(area_number));
-local data = get_data("KRP")..tostring(area_number)
+local data = get_data("KRP")..tostring(area_number);
 ```
 > **Rationale:** It is not obvious at a glace what the precedence rules are
 when omitting the parentheses in a function call. Can you quickly tell which
 of the two "good" examples in equivalent to the "bad" one? (It's the second
 argument on a single line. You may do so for table arguments that span several
 lines.
 ```lua
 local an_instance = a_module.new {
-a_parameter = 42,
+a_parameter = 42;
-another_parameter = "yay",
+another_parameter = "yay";
 }
 ```
 > **Rationale:** The use as in `a_module.new` above occurs alone in a statement,
 so there are no precedence issues.
 * Use dot notation when accessing known properties.
 ```lua
 local luke = {
-jedi = true,
+jedi = true;
-age = 28,
+age = 28;
 }
 -- bad
 local is_jedi = luke["jedi"]
 -- good
-local is_jedi = luke.jedi
+local is_jedi = luke.jedi;
 ```
 * Use subscript notation `[]` when accessing properties with a variable or if using a table as a list.
 ```lua
 local vehicles = load_vehicles_from_disk("vehicles.dat")
 if vehicles["Porsche"] then
-porsche_handler(vehicles["Porsche"])
+porsche_handler(vehicles["Porsche"]);
-vehicles["Porsche"] = nil
+vehicles["Porsche"] = nil;
 end
 for name, cars in pairs(vehicles) do
-regular_handler(cars)
+regular_handler(cars);
 end
 ```
 > **Rationale:** Using dot notation makes it clearer that the given key is meant
 to be used as a record/object field.
 ## Functions in tables
 * When declaring modules and classes, declare functions external to the table definition:
 ```lua
-local my_module = {}
+local my_module = {};
 function my_module.a_function(x)
 -- code
 end
 ```
 ```lua
 -- bad
 superpower = get_superpower()
 -- good
-local superpower = get_superpower()
+local superpower = get_superpower();
 ```
 > **Rationale:** Not doing so will result in global variables to avoid polluting
 the global namespace.
 return name
 end
 -- good
 local bad = function()
-test()
+test();
-print("doing stuff..")
+print("doing stuff..");
 --...other stuff...
-local name = get_name()
+local name = get_name();
 if name == "test" then
-return false
+return false;
 end
-return name
+return name;
 end
 ```
 > **Rationale:** Lua has proper lexical scoping. Declaring the function later means that its
 scope is smaller, so this makes it easier to check for the effects of a variable.
 easier to scan visually:
 ```lua
 local function default_name(name)
 -- return the default "Waldo" if name is nil
-return name or "Waldo"
+return name or "Waldo";
 end
 local function brew_coffee(machine)
-return (machine and machine.is_loaded) and "coffee brewing" or "fill your water"
+return (machine and machine.is_loaded) and "coffee brewing" or "fill your water";
 end
 ```
 Note that the `x and y or z` as a substitute for `x ? y : z` does not work if
 `y` may be `nil` or `false` so avoid it altogether for returning booleans or
 -- good
 if not ok then return nil, "this failed for this reason: " .. reason end
 -- good
-use_callback(x, function(k) return k.last end)
+use_callback(x, function(k) return k.last end);
 -- good
 if test then
 return false
 end
 -- bad
 if test < 1 and do_complicated_function(test) == false or seven == 8 and nine == 10 then do_other_complicated_function() end
 -- good
 if test < 1 and do_complicated_function(test) == false or seven == 8 and nine == 10 then
-do_other_complicated_function()
+do_other_complicated_function();
-return false
+return false;
 end
 ```
 * Separate statements onto multiple lines. Use semicolons as statement terminators.
 age="1 year",
 breed="Bernese Mountain Dog"
 })
 -- good
-local x = y * 9
+local x = y * 9;
-local numbers = {1, 2, 3}
+local numbers = {1, 2, 3};
 local strings = {
 "hello";
 "Lua";
 "world";
 }
 dog.set("attr", {
-age = "1 year",
+age = "1 year";
-breed = "Bernese Mountain Dog",
+breed = "Bernese Mountain Dog";
-})
+});
 ```
 * Indent tables and functions according to the start of the line, not the construct:
 ```lua
 local my_table = {
 "hello";
 "world";
 }
 using_a_callback(x, function(...)
-print("hello")
+print("hello");
 end)
 ```
 > **Rationale:** This keep indentation levels aligned at predictable places. You don't
 need to realign the entire block if something in the first line changes (such as
 * The concatenation operator gets a pass for avoiding spaces:
 ```lua
 -- okay
-local message = "Hello, "..user.."! This is your day # "..day.." in our platform!"
+local message = "Hello, "..user.."! This is your day # "..day.." in our platform!";
 ```
 > **Rationale:** Being at the baseline, the dots already provide some visual spacing.
 * No spaces after the name of a function in a declaration or in its arguments:
 -- bad
 local a               = 1
 local long_identifier = 2
 -- good
-local a = 1
+local a = 1;
-local long_identifier = 2
+local long_identifier = 2;
 ```
 > **Rationale:** This produces extra diffs which add noise to `git blame`.
 * Alignment is occasionally useful when logical correspondence is to be highlighted:
 ```lua
 -- okay
-sys_command(form, UI_FORM_UPDATE_NODE, "a",      FORM_NODE_HIDDEN,  false)
+sys_command(form, UI_FORM_UPDATE_NODE, "a",      FORM_NODE_HIDDEN,  false);
-sys_command(form, UI_FORM_UPDATE_NODE, "sample", FORM_NODE_VISIBLE, false)
+sys_command(form, UI_FORM_UPDATE_NODE, "sample", FORM_NODE_VISIBLE, false);
 ```
 ## Typing
 * In non-performance critical code, it can be useful to add type-checking assertions
 for function arguments:
 ```lua
 function manif.load_manifest(repo_url, lua_version)
-assert(type(repo_url) == "string")
+assert(type(repo_url) == "string");
-assert(type(lua_version) == "string" or not lua_version)
+assert(type(lua_version) == "string" or not lua_version);
 -- ...
 end
 ```
 ```lua
 -- bad
 local total_score = review_score .. ""
 -- good
-local total_score = tostring(review_score)
+local total_score = tostring(review_score);
 ```
 ## Errors
 * Functions that can fail for reasons that are expected (e.g. I/O) should
 Follow [these guidelines](http://hisham.hm/2014/01/02/how-to-write-lua-modules-in-a-post-module-world/) for writing modules. In short:
 * Always require a module into a local variable named after the last component of the module’s full name.
 ```lua
-local bar = require("foo.bar") -- requiring the module
+local bar = require("foo.bar"); -- requiring the module
-bar.say("hello") -- using the module
+bar.say("hello"); -- using the module
 ```
 * Don’t rename modules arbitrarily:
 ```lua
 name that will be used to require it. You may use an LDoc comment to identify
 the whole module path.
 ```lua
 --- @module foo.bar
-local bar = {}
+local bar = {};
 ```
 * Try to use names that won't clash with your local variables. For instance, don't
 name your module something like “size”.
 * Public functions are declared in the module table, with dot syntax:
 ```lua
 function bar.say(greeting)
-print(greeting)
+print(greeting);
 end
 ```
 > **Rationale:** Visibility rules are made explicit through syntax.
 and do something like this instead:
 ```lua
 -- good
-local messagepack = require("messagepack")
+local messagepack = require("messagepack");
-local mpack = messagepack.new({integer = "unsigned"})
+local mpack = messagepack.new({integer = "unsigned"});
 ```
 * The invocation of require may omit parentheses around the module name:
 ```lua
-local bla = require "bla"
+local bla = require "bla";
 ```
 ## Metatables, classes and objects
 If creating a new type of object that has a metatable and methods, the
 ```
 -- bad
 my_object.my_method(my_object)
 -- good
-my_object:my_method()
+my_object:my_method();
 ```
 > **Rationale:** This makes it explicit that the intent is to use the function as a method.
 * Do not rely on the `__gc` metamethod to release resources other than memory.
 reasons (e.g. a callback that follows a given format) but doesn't use some of
 its arguments; it's better to spell out in the argument what the API the
 function implements is, instead of adding `_` variables.
 ```
-local foo, bar = some_function() --luacheck: ignore 212/foo
+local foo, bar = some_function(); --luacheck: ignore 212/foo
-print(bar)
+print(bar);
 ```
 * luacheck warning 542 (empty if branch) can also be ignored, when a sequence
 of `if`/`elseif`/`else` blocks implements a "switch/case"-style list of cases,
 and one of the cases is meant to mean "pass". For example:
 ```lua
 if warning >= 600 and warning <= 699 then
-print("no whitespace warnings")
+print("no whitespace warnings");
 elseif warning == 542 then --luacheck: ignore 542
 -- pass
 else
-print("got a warning: "..warning)
+print("got a warning: "..warning);
 end
 ```
 > **Rationale:** This avoids writing negated conditions in the final fallback
 case, and it's easy to add another case to the construct without having to

Mercurial > prosody-hg

comparison doc/coding_style.md @ 9939:3a7f822f6edd