mirrors
/
rspamd
mirror of https://github.com/vstakhov/rspamd.git
Watch 1
Star 0
Fork 0
Code Issues 0 Releases 159 Wiki Activity
Browse Source

[Minor] Doc: Add Lua style guide

tags/1.9.0
Vsevolod Stakhov 5 years ago
parent
178c262919
commit
51b39f712d
1 changed files with 733 additions and 0 deletions
Split View Show Diff Stats
  1. 733
    0
      lua_style.md

+ 733
- 0
lua_style.md View File

@@ -0,0 +1,733 @@
# Lua Style Guide

This style guide contains a list of guidelines that we try to follow for Rspamd.

This guide is forked from https://github.com/Olivine-Labs/lua-style-guide


## <a name='TOC'>Table of Contents</a>

1. [Types](#types)
1. [Tables](#tables)
1. [Strings](#strings)
1. [Functions](#functions)
1. [Properties](#properties)
1. [Variables](#variables)
1. [Conditional Expressions & Equality](#conditionals)
1. [Blocks](#blocks)
1. [Whitespace](#whitespace)
1. [Commas](#commas)
1. [Semicolons](#semicolons)
1. [Type Casting & Coercion](#type-coercion)
1. [Naming Conventions](#naming-conventions)
1. [Accessors](#accessors)
1. [Constructors](#constructors)
1. [Modules](#modules)
1. [Testing](#testing)
1. [License](#license)

## <a name='types'>Types</a>

- **Primitives**: When you access a primitive type you work directly on its value

+ `string`
+ `number`
+ `boolean`
+ `nil`

```lua
local foo = 1
local bar = foo

bar = 9

print(foo, bar) -- => 1 9
```

- **Complex**: When you access a complex type you work on a reference to its value

+ `table`
+ `function`
+ `userdata`

```lua
local foo = { 1, 2 }
local bar = foo

bar[0] = 9
foo[1] = 3

print(foo[0], bar[0]) -- => 9 9
print(foo[1], bar[1]) -- => 3 3
print(foo[2], bar[2]) -- => 2 2
```

**[[⬆]](#TOC)**

## <a name='tables'>Tables</a>

- Use the constructor syntax for table property creation where possible.

```lua
-- bad
local player = {}
player.name = 'Jack'
player.class = 'Rogue'

-- good
local player = {
name = 'Jack',
class = 'Rogue'
}
```

- Define functions externally to table definition.

```lua
-- bad
local player = {
attack = function()
-- ...stuff...
end
}

-- good
local function attack()
end

local player = {
attack = attack
}
```

**[[⬆]](#TOC)**

## <a name='strings'>Strings</a>

- Use single quotes `''` for strings.

```lua
-- bad
local name = "Bob Parr"

-- good
local name = 'Bob Parr'

-- bad
local fullName = "Bob " .. self.lastName

-- good
local fullName = 'Bob ' .. self.lastName
```

- Strings longer than 80 characters should be written across multiple lines
using concatenation. This allows you to indent nicely.

```lua
-- bad
local errorMessage = 'This is a super long error that was thrown because of Batman. When you stop to think about how Batman had anything to do with this, you would get nowhere fast.'

-- bad
local errorMessage = 'This is a super long error that \
was thrown because of Batman. \
When you stop to think about \
how Batman had anything to do \
with this, you would get nowhere \
fast.'


-- bad
local errorMessage = [[This is a super long error that
was thrown because of Batman.
When you stop to think about
how Batman had anything to do
with this, you would get nowhere
fast.]]

-- good
local errorMessage = 'This is a super long error that ' ..
'was thrown because of Batman. ' ..
'When you stop to think about ' ..
'how Batman had anything to do ' ..
'with this, you would get nowhere ' ..
'fast.'
```

**[[⬆]](#TOC)**


## <a name='functions'>Functions</a>
- Prefer lots of small functions to large, complex functions. [Smalls Functions Are Good For The Universe](http://kikito.github.io/blog/2012/03/16/small-functions-are-good-for-the-universe/).

- Prefer function syntax over variable syntax. This helps differentiate
between named and anonymous functions.

```lua
-- bad
local nope = function(name, options)
-- ...stuff...
end

-- good
local function yup(name, options)
-- ...stuff...
end
```

- Never name a parameter `arg`, this will take precendence over the `arg` object that is given to every function scope in older versions of Lua.

```lua
-- bad
local function nope(name, options, arg)
-- ...stuff...
end

-- good
local function yup(name, options, ...)
-- ...stuff...
end
```

- Perform validation early and return as early as possible.

```lua
-- bad
local is_good_name = function(name, options, arg)
local is_good = #name > 3
is_good = is_good and #name < 30

-- ...stuff...

return is_bad
end

-- good
local is_good_name = function(name, options, args)
if #name < 3 or #name > 30 then return false end

-- ...stuff...

return true
end
```

**[[⬆]](#TOC)**


## <a name='properties'>Properties</a>

- Use dot notation when accessing known properties.

```lua
local luke = {
jedi = true,
age = 28
}

-- bad
local isJedi = luke['jedi']

-- good
local isJedi = luke.jedi
```

- Use subscript notation `[]` when accessing properties with a variable
or if using a table as a list.

```lua
local luke = {
jedi = true,
age = 28
}

local function getProp(prop)
return luke[prop]
end

local isJedi = getProp('jedi')
```

**[[⬆]](#TOC)**


## <a name='variables'>Variables</a>

- Always use `local` to declare variables. Not doing so will result in
global variables to avoid polluting the global namespace.

```lua
-- bad
superPower = SuperPower()

-- good
local superPower = SuperPower()
```

- Assign variables at the top of their scope where possible. This makes it
easier to check for existing variables.

```lua
-- bad
local bad = function()
test()
print('doing stuff..')

//..other stuff..

local name = getName()

if name == 'test' then
return false
end

return name
end

-- good
local function good()
local name = getName()

test()
print('doing stuff..')

//..other stuff..

if name == 'test' then
return false
end

return name
end
```

**[[⬆]](#TOC)**


## <a name='conditionals'>Conditional Expressions & Equality</a>

- False and nil are *falsy* in conditional expressions. All else is true.

```lua
local str = ''

if str then
-- true
end
```

- Use shortcuts when you can, unless you need to know the difference between
false and nil.

```lua
-- bad
if name ~= nil then
-- ...stuff...
end

-- good
if name then
-- ...stuff...
end
```

- Prefer *true* statements over *false* statements where it makes sense.
Prioritize truthy conditions when writing multiple conditions.

```lua
--bad
if not thing then
-- ...stuff...
else
-- ...stuff...
end

--good
if thing then
-- ...stuff...
else
-- ...stuff...
end
```

- Prefer defaults to `else` statements where it makes sense. This results in
less complex and safer code at the expense of variable reassignment, so
situations may differ.

```lua
--bad
local function full_name(first, last)
local name

if first and last then
name = first .. ' ' .. last
else
name = 'John Smith'
end

return name
end

--good
local function full_name(first, last)
local name = 'John Smith'

if first and last then
name = first .. ' ' .. last
end

return name
end
```

- Short ternaries are okay.

```lua
local function default_name(name)
-- return the default 'Waldo' if name is nil
return name or 'Waldo'
end

local function brew_coffee(machine)
return machine and machine.is_loaded and 'coffee brewing' or 'fill your water'
end
```


**[[⬆]](#TOC)**


## <a name='blocks'>Blocks</a>

- Single line blocks are okay for *small* statements. Try to keep lines to 80 characters.
Indent lines if they overflow past the limit.

```lua
-- good
if test then return false 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()
return false
end
```

**[[⬆]](#TOC)**


## <a name='whitespace'>Whitespace</a>

- Use soft tabs set to 2 spaces.

```lua
-- bad
function()
∙∙∙∙local name
end

-- bad
function()
∙local name
end

-- good
function()
∙∙local name
end
```

- Place 1 space before opening and closing braces. Place no spaces around parens.

```lua
-- bad
local test = {one=1}

-- good
local test = { one = 1 }

-- bad
dog.set('attr',{
age = '1 year',
breed = 'Bernese Mountain Dog'
})

-- good
dog.set('attr', {
age = '1 year',
breed = 'Bernese Mountain Dog'
})
```

- Place an empty newline at the end of the file.

```lua
-- bad
(function(global)
-- ...stuff...
end)(self)
```

```lua
-- good
(function(global)
-- ...stuff...
end)(self)

```

- Surround operators with spaces.

```lua
-- bad
local thing=1
thing = thing-1
thing = thing*1
thing = 'string'..'s'

-- good
local thing = 1
thing = thing - 1
thing = thing * 1
thing = 'string' .. 's'
```

- Use one space after commas.

```lua
--bad
local thing = {1,2,3}
thing = {1 , 2 , 3}
thing = {1 ,2 ,3}

--good
local thing = {1, 2, 3}
```

- Add a line break after multiline blocks.

```lua
--bad
if thing then
-- ...stuff...
end
function derp()
-- ...stuff...
end
local wat = 7

--good
if thing then
-- ...stuff...
end

function derp()
-- ...stuff...
end

local wat = 7
```

- Delete unnecessary whitespace at the end of lines.

**[[⬆]](#TOC)**

## <a name='commas'>Commas</a>

- Leading commas aren't okay. An ending comma on the last item is okay but discouraged.

```lua
-- bad
local thing = {
once = 1
, upon = 2
, aTime = 3
}

-- good
local thing = {
once = 1,
upon = 2,
aTime = 3
}

-- okay
local thing = {
once = 1,
upon = 2,
aTime = 3,
}
```

**[[⬆]](#TOC)**


## <a name='semicolons'>Semicolons</a>

- **Nope.** Separate statements onto multiple lines.

```lua
-- bad
local whatever = 'sure';
a = 1; b = 2

-- good
local whatever = 'sure'
a = 1
b = 2
```

**[[⬆]](#TOC)**


## <a name='type-coercion'>Type Casting & Coercion</a>

- Perform type coercion at the beginning of the statement. Use the built-in functions. (`tostring`, `tonumber`, etc.)

- Use `tostring` for strings if you need to cast without string concatenation.

```lua
-- bad
local totalScore = reviewScore .. ''

-- good
local totalScore = tostring(reviewScore)
```

- Use `tonumber` for Numbers.

```lua
local inputValue = '4'

-- bad
local val = inputValue * 1

-- good
local val = tonumber(inputValue)
```

**[[⬆]](#TOC)**


## <a name='naming-conventions'>Naming Conventions</a>

- Avoid single letter names. Be descriptive with your naming. You can get
away with single-letter names when they are variables in loops.

```lua
-- bad
local function q()
-- ...stuff...
end

-- good
local function query()
-- ..stuff..
end
```

- Use underscores for ignored variables in loops.

```lua
--good
for _, name in pairs(names) do
-- ...stuff...
end
```

- Use snake_case when naming objects, functions, and instances. Tend towards
verbosity if unsure about naming.

```lua
-- bad
local OBJEcttsssss = {}
local thisIsMyObject = {}

local c = function()
-- ...stuff...
end

-- good
local this_is_my_object = {}

local function do_that_thing()
-- ...stuff...
end
```

- Use PascalCase for factories.

```lua
-- bad
local player = require('player')

-- good
local Player = require('player')
local me = Player({ name = 'Jack' })
```

**[[⬆]](#TOC)**

- Use `is` or `has` for boolean-returning functions that are part of tables.

```lua
--bad
local function evil(alignment)
return alignment < 100
end

--good
local function is_evil(alignment)
return alignment < 100
end
```

## <a name='modules'>Modules</a>

- The module should return a table or function.
- The module should not use the global namespace for anything ever. The
module should be a closure.
- The file should be named like the module.

```lua
-- thing.lua
local thing = { }

local meta = {
__call = function(self, key, vars)
print key
end
}


return setmetatable(thing, meta)
```

- Note that modules are [loaded as singletons](http://lua-users.org/wiki/TheEssenceOfLoadingCode)
and therefore should usually be factories (a function returning a new instance of a table)
unless static (like utility libraries.)

**[[⬆]](#TOC)**

## <a name='testing'>Testing</a>

- Use [telescope](https://github.com/norman/telescope) for unit tests and Robot framework for functional testing.
Unit tests can rely on LuaJIT ffi module if C function testing is required.

**[[⬆]](#TOC)**

## <a name='license'>License</a>

- Released under CC0 (Public Domain).
Information can be found at [http://creativecommons.org/publicdomain/zero/1.0/](http://creativecommons.org/publicdomain/zero/1.0/).

**[[⬆]](#TOC)**

Write Preview
Loading…
Cancel
Save