Skip to content

Commit

Permalink
Fix feedback issues (#3614)
Browse files Browse the repository at this point in the history
  • Loading branch information
@andreyaksenov
andreyaksenov authored Aug 11, 2023
1 parent d21a9a7 commit 9918cb3
Show file tree
Hide file tree
Showing 7 changed files with 106 additions and 86 deletions.
2 changes: 1 addition & 1 deletion doc/concepts/coop_multitasking.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ transfers control of the thread from the current fiber to another fiber that is
Any live fiber can be in one of three states: ``running``, ``suspended``, and
``ready``. After a fiber dies, the ``dead`` status is returned. By observing
fibers from the outside, you can only see ``running`` (for the current fiber)
and ``suspended`` for any other fiber waiting for an event from eventloop (``ev``)
and ``suspended`` for any other fiber waiting for an event from the event loop (``ev``)
for execution.

.. image:: yields.svg
Expand Down
150 changes: 83 additions & 67 deletions doc/dev_guide/lua_style_guide.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -65,16 +65,19 @@ Indentation and formatting

.. code-block:: lua
-- Good
if (a == true and b == false) or (a == false and b == true) then
<...>
end -- good
end
-- Bad
if a == true and b == false or a == false and b == true then
<...>
end -- bad
end
-- Good but not explicit
if a ^ b == true then
end -- good, but not explicit
end
* Type conversion

Expand All @@ -83,31 +86,32 @@ Indentation and formatting

.. code-block:: lua
-- Bad
local a = 123
a = a .. ''
-- bad
-- Good
local a = 123
a = tostring(a)
-- good
-- Bad
local a = '123'
a = a + 5 -- 128
-- bad
-- Good
local a = '123'
a = tonumber(a) + 5 -- 128
-- good
* Try to avoid multiple nested ``if``'s with common body:

.. code-block:: lua
-- Good
if (a == true and b == false) or (a == false and b == true) then
do_something()
end
-- good
-- Bad
if a == true then
if b == false then
do_something()
Expand All @@ -117,56 +121,59 @@ Indentation and formatting
do_something()
end
end
-- bad
* Avoid multiple concatenations in one statement, use ``string.format`` instead:

.. code-block:: lua
-- Bad
function say_greeting(period, name)
local a = "good " .. period .. ", " .. name
end
-- bad
-- Good
function say_greeting(period, name)
local a = string.format("good %s, %s", period, name)
end
-- good
-- Best
local say_greeting_fmt = "good %s, %s"
function say_greeting(period, name)
local a = say_greeting_fmt:format(period, name)
end
-- best
* Use ``and``/``or`` for default variable values

.. code-block:: lua
-- Good
function(input)
input = input or 'default_value'
end -- good
end
-- Ok but excessive
function(input)
if input == nil then
input = 'default_value'
end
end -- ok, but excessive
end
* ``if``'s and return statements:

.. code-block:: lua
-- Good
if a == true then
return do_something()
end
do_other_thing() -- good
do_other_thing()
-- Bad
if a == true then
return do_something()
else
do_other_thing()
end -- bad
end
* Using spaces:

Expand All @@ -175,69 +182,71 @@ Indentation and formatting

.. code-block:: lua
-- Bad
function name (arg1,arg2,...)
end -- bad
end
-- Good
function name(arg1, arg2, ...)
end -- good
end
- Add a space after comment markers:

.. code-block:: lua
while true do -- inline comment
-- comment
do_something()
while true do -- Inline comment
-- Comment
do_something()
end
--[[
multiline
Multiline
comment
]]--
- Surrounding operators:

.. code-block:: lua
-- Bad
local thing=1
thing = thing-1
thing = thing*1
thing = 'string'..'s'
-- bad
-- Good
local thing = 1
thing = thing - 1
thing = thing * 1
thing = 'string' .. 's'
-- good
- Add a space after commas in tables:

.. code-block:: lua
-- Bad
local thing = {1,2,3}
thing = {1 , 2 , 3}
thing = {1 ,2 ,3}
-- bad
-- Good
local thing = {1, 2, 3}
-- good
- Add a space in map definitions after equals signs and commas:

.. code-block:: lua
-- Bad
return {1,2,3,4}
return {
key1 = val1,key2=val2
}
-- bad
-- Good
return {1, 2, 3, 4}
return {
key1 = val1, key2 = val2,
key3 = vallll
key3 = val3
}
-- good
You can also use alignment:

Expand All @@ -258,25 +267,25 @@ Indentation and formatting

.. code-block:: lua
-- Bad
if thing ~= nil then
-- ...stuff...
-- ... stuff ...
end
function derp()
-- ...stuff...
-- ... stuff ...
end
local wat = 7
-- bad
-- Good
if thing ~= nil then
-- ...stuff...
-- ... stuff ...
end
function derp()
-- ...stuff...
-- ... stuff ...
end
local wat = 7
-- good
- Delete whitespace at EOL (strongly forbidden. Use ``:s/\s\+$//gc`` in vim
to delete them).
Expand All @@ -290,14 +299,18 @@ add a prefix, or add a table instead of a prefix:

.. code-block:: lua
-- Very bad
function bad_global_example()
end -- very, very bad
end
function good_local_example()
end
_G.modulename_good_local_example = good_local_example -- good
-- Good
_G.modulename_good_local_example = good_local_example
-- Better
_G.modulename = {}
_G.modulename.good_local_example = good_local_example -- better
_G.modulename.good_local_example = good_local_example
Always use a prefix to avoid name conflicts.

Expand Down Expand Up @@ -369,11 +382,11 @@ To write modules, use one of the two patterns (don't use ``modules()``):
local M = {}
function M.foo()
...
...
end
function M.bar()
...
...
end
return M
Expand All @@ -383,16 +396,16 @@ or
.. code-block:: lua
local function foo()
...
...
end
local function bar()
...
...
end
return {
foo = foo,
bar = bar,
foo = foo,
bar = bar,
}
Commenting
Expand All @@ -401,17 +414,19 @@ Commenting
Don't forget to comment your Lua code. You shouldn't comment Lua syntax (assume that the reader already
knows the Lua language). Instead, tell about functions/variable names/etc.

Start a sentence with a capital letter and end with a period.

Multiline comments: use matching (``--[[ ]]--``) instead of simple
(``--[[ ]]``).

Public function comments:

.. code-block:: lua
--- Copy any table (shallow and deep version)
--- Copy any table (shallow and deep version).
-- * deepcopy: copies all levels
-- * shallowcopy: copies only first level
-- Supports __copy metamethod for copying custom tables with metatables
-- Supports __copy metamethod for copying custom tables with metatables.
-- @function gsplit
-- @table inp original table
-- @shallow[opt] sep flag for shallow copy
Expand All @@ -429,43 +444,44 @@ Use the ``tap`` module for writing efficient tests. Example of a test file:
local test = require('tap').test('table')
test:plan(31)
do -- check basic table.copy (deepcopy)
do
-- Check basic table.copy (deepcopy).
local example_table = {
{1, 2, 3},
{"help, I'm very nested", {{{ }}} }
{ 1, 2, 3 },
{ "help, I'm very nested", { { { } } } }
}
local copy_table = table.copy(example_table)
test:is_deeply(
example_table,
copy_table,
"checking, that deepcopy behaves ok"
example_table,
copy_table,
"checking, that deepcopy behaves ok"
)
test:isnt(
example_table,
copy_table,
"checking, that tables are different"
example_table,
copy_table,
"checking, that tables are different"
)
test:isnt(
example_table[1],
copy_table[1],
"checking, that tables are different"
example_table[1],
copy_table[1],
"checking, that tables are different"
)
test:isnt(
example_table[2],
copy_table[2],
"checking, that tables are different"
example_table[2],
copy_table[2],
"checking, that tables are different"
)
test:isnt(
example_table[2][2],
copy_table[2][2],
"checking, that tables are different"
example_table[2][2],
copy_table[2][2],
"checking, that tables are different"
)
test:isnt(
example_table[2][2][1],
copy_table[2][2][1],
"checking, that tables are different"
example_table[2][2][1],
copy_table[2][2][1],
"checking, that tables are different"
)
end
Expand Down
Loading

0 comments on commit 9918cb3

Please sign in to comment.