└── README.md /README.md: -------------------------------------------------------------------------------- 1 | 2 | # Lua Style Guide 3 | 4 | This style guides lists the coding conventions used in the 5 | [LuaRocks](http://github.com/luarocks/luarocks) project. It does not claim to 6 | be the best Lua coding style in the planet, but it is used successfully in a 7 | long-running project, and we do provide rationale for many of the design 8 | decisions listed below. 9 | 10 | The list of recommendations in this document was based on the ones mentioned 11 | in the following style guides: (sometimes copying material verbatim, sometimes 12 | giving the opposite advice! :) ) 13 | 14 | * https://github.com/Olivine-Labs/lua-style-guide/ 15 | * https://github.com/zaki/lua-style-guide 16 | * http://lua-users.org/wiki/LuaStyleGuide 17 | * http://sputnik.freewisdom.org/en/Coding_Standard 18 | * https://gist.github.com/catwell/b3c01dbea413aa78675740546dfd5ce2 19 | 20 | ## Indentation and formatting 21 | 22 | * Let's address the elephant in the room first. LuaRocks is indented with 3 spaces. 23 | 24 | ```lua 25 | for i, pkg in ipairs(packages) do 26 | for name, version in pairs(pkg) do 27 | if name == searched then 28 | print(version) 29 | end 30 | end 31 | end 32 | ``` 33 | 34 | > **Rationale:** There is no agreement in the Lua community as for indentation, so 35 | 3 spaces lies nicely as a middle ground between the 2-space camp and the 36 | 4-space camp. Also, for a language that nests with `do`/`end` blocks, it 37 | produces pleasant-looking block-closing staircases, as in the example above. 38 | 39 | * One should not use tabs for indentation, or mix it with spaces. 40 | 41 | * Use LF (Unix) line endings. 42 | 43 | ## Documentation 44 | 45 | * Document function signatures using 46 | [LDoc](https://stevedonovan.github.io/ldoc/). Specifying typing information 47 | after each parameter or return value is a nice plus. 48 | 49 | ```lua 50 | --- Load a local or remote manifest describing a repository. 51 | -- All functions that use manifest tables assume they were obtained 52 | -- through either this function or load_local_manifest. 53 | -- @param repo_url string: URL or pathname for the repository. 54 | -- @param lua_version string: Lua version in "5.x" format, defaults to installed version. 55 | -- @return table or (nil, string, [string]): A table representing the manifest, 56 | -- or nil followed by an error message and an optional error code. 57 | function manif.load_manifest(repo_url, lua_version) 58 | -- code 59 | end 60 | ``` 61 | 62 | * Use `TODO` and `FIXME` tags in comments. `TODO` indicates a missing feature 63 | to be implemented later. `FIXME` indicates a problem in the existing code 64 | (inefficient implementation, bug, unnecessary code, etc). 65 | 66 | ```lua 67 | -- TODO: implement method 68 | local function something() 69 | -- FIXME: check conditions 70 | end 71 | ``` 72 | 73 | * Prefer LDoc comments over the function that explain _what_ the function does 74 | than inline comments inside the function that explain _how_ it does it. Ideally, 75 | the implementation should be simple enough so that comments aren't needed. If 76 | the function grows complex, split it into multiple functions so that their names 77 | explain what each part does. 78 | 79 | ## Variable names 80 | 81 | * Variable names with larger scope should be more descriptive than those with 82 | smaller scope. One-letter variable names should be avoided except for very 83 | small scopes (less than ten lines) or for iterators. 84 | 85 | * `i` should be used only as a counter variable in for loops (either numeric for 86 | or `ipairs`). 87 | 88 | * Prefer more descriptive names than `k` and `v` when iterating with `pairs`, 89 | unless you are writing a function that operates on generic tables. 90 | 91 | * Use `_` for ignored variables (e.g. in for loops:) 92 | 93 | ```lua 94 | for _, item in ipairs(items) do 95 | do_something_with_item(item) 96 | end 97 | ``` 98 | 99 | * Variables and function names should use `snake_case`. 100 | 101 | ```lua 102 | -- bad 103 | local OBJEcttsssss = {} 104 | local thisIsMyObject = {} 105 | local c = function() 106 | -- ...stuff... 107 | end 108 | 109 | -- good 110 | local this_is_my_object = {} 111 | 112 | local function do_that_thing() 113 | -- ...stuff... 114 | end 115 | ``` 116 | 117 | > **Rationale:** The standard library uses lowercase APIs, with `joinedlowercase` 118 | names, but this does not scale too well for more complex APIs. `snake_case` 119 | tends to look good enough and not too out-of-place along side the standard 120 | APIs. 121 | 122 | * When doing OOP, classes should use `CamelCase`. Acronyms (e.g. XML) should 123 | only uppercase the first letter (`XmlDocument`). Methods use `snake_case` too. 124 | In LuaRocks, this is used in the `Api` object in the `luarocks.upload.api` 125 | module. 126 | 127 | ```lua 128 | for _, name in pairs(names) do 129 | -- ...stuff... 130 | end 131 | ``` 132 | 133 | * Prefer using `is_` when naming boolean functions: 134 | 135 | ```lua 136 | -- bad 137 | local function evil(alignment) 138 | return alignment < 100 139 | end 140 | 141 | -- good 142 | local function is_evil(alignment) 143 | return alignment < 100 144 | end 145 | ``` 146 | 147 | * `UPPER_CASE` is to be used sparingly, with "constants" only. 148 | 149 | > **Rationale:** "Sparingly", since Lua does not have real constants. This 150 | notation is most useful in libraries that bind C libraries, when bringing over 151 | constants from C. 152 | 153 | * Do not use uppercase names starting with `_`, they are reserved by Lua. 154 | 155 | ## Tables 156 | 157 | * When creating a table, prefer populating its fields all at once, if possible: 158 | 159 | ```lua 160 | local player = { 161 | name = "Jack", 162 | class = "Rogue", 163 | } 164 | ``` 165 | 166 | * You can add a trailing comma to all fields, including the last one. 167 | 168 | > **Rationale:** This makes the structure of your tables more evident at a glance. 169 | Trailing commas make it quicker to add new fields and produces shorter diffs. 170 | 171 | * Use plain `key` syntax whenever possible, use `["key"]` syntax when using names 172 | that can't be represented as identifiers and avoid mixing representations in 173 | a declaration: 174 | 175 | ```lua 176 | table = { 177 | ["1394-E"] = val1, 178 | ["UTF-8"] = val2, 179 | ["and"] = val2, 180 | } 181 | ``` 182 | 183 | ## Strings 184 | 185 | * Use `"double quotes"` for strings; use `'single quotes'` when writing strings 186 | that contain double quotes. 187 | 188 | ```lua 189 | local name = "LuaRocks" 190 | local sentence = 'The name of the program is "LuaRocks"' 191 | ``` 192 | 193 | > **Rationale:** Double quotes are used as string delimiters in a larger number of 194 | programming languages. Single quotes are useful for avoiding escaping when 195 | using double quotes in literals. 196 | 197 | ## Line lengths 198 | 199 | * There are no hard or soft limits on line lengths. Line lengths are naturally 200 | limited by using one statement per line. If that still produces lines that are 201 | too long (e.g. an expression that produces a line over 256-characters long, 202 | for example), this means the expression is too complex and would do better 203 | split into subexpressions with reasonable names. 204 | 205 | > **Rationale:** No one works on VT100 terminals anymore. If line lengths are a proxy 206 | for code complexity, we should address code complexity instead of using line 207 | breaks to fit mind-bending statements over multiple lines. 208 | 209 | ## Function declaration syntax 210 | 211 | * Prefer function syntax over variable syntax. This helps differentiate between 212 | named and anonymous functions. 213 | 214 | ```lua 215 | -- bad 216 | local nope = function(name, options) 217 | -- ...stuff... 218 | end 219 | 220 | -- good 221 | local function yup(name, options) 222 | -- ...stuff... 223 | end 224 | ``` 225 | 226 | * Perform validation early and return as early as possible. 227 | 228 | ```lua 229 | -- bad 230 | local function is_good_name(name, options, arg) 231 | local is_good = #name > 3 232 | is_good = is_good and #name < 30 233 | 234 | -- ...stuff... 235 | 236 | return is_good 237 | end 238 | 239 | -- good 240 | local function is_good_name(name, options, args) 241 | if #name < 3 or #name > 30 then 242 | return false 243 | end 244 | 245 | -- ...stuff... 246 | 247 | return true 248 | end 249 | ``` 250 | 251 | ## Function calls 252 | 253 | * Even though Lua allows it, do not omit parenthesis for functions that take a 254 | unique string literal argument. 255 | 256 | ```lua 257 | -- bad 258 | local data = get_data"KRP"..tostring(area_number) 259 | -- good 260 | local data = get_data("KRP"..tostring(area_number)) 261 | local data = get_data("KRP")..tostring(area_number) 262 | ``` 263 | 264 | > **Rationale:** It is not obvious at a glace what the precedence rules are 265 | when omitting the parentheses in a function call. Can you quickly tell which 266 | of the two "good" examples in equivalent to the "bad" one? (It's the second 267 | one). 268 | 269 | * You should not omit parenthesis for functions that take a unique table 270 | argument on a single line. You may do so for table arguments that span several 271 | lines. 272 | 273 | ```lua 274 | local an_instance = a_module.new { 275 | a_parameter = 42, 276 | another_parameter = "yay", 277 | } 278 | ``` 279 | 280 | > **Rationale:** The use as in `a_module.new` above occurs alone in a statement, 281 | so there are no precedence issues. 282 | 283 | ## Table attributes 284 | 285 | * Use dot notation when accessing known properties. 286 | 287 | ```lua 288 | local luke = { 289 | jedi = true, 290 | age = 28, 291 | } 292 | 293 | -- bad 294 | local is_jedi = luke["jedi"] 295 | 296 | -- good 297 | local is_jedi = luke.jedi 298 | ``` 299 | 300 | * Use subscript notation `[]` when accessing properties with a variable or if using a table as a list. 301 | 302 | ```lua 303 | local vehicles = load_vehicles_from_disk("vehicles.dat") 304 | 305 | if vehicles["Porsche"] then 306 | porsche_handler(vehicles["Porsche"]) 307 | vehicles["Porsche"] = nil 308 | end 309 | for name, cars in pairs(vehicles) do 310 | regular_handler(cars) 311 | end 312 | ``` 313 | 314 | > **Rationale:** Using dot notation makes it clearer that the given key is meant 315 | to be used as a record/object field. 316 | 317 | ## Functions in tables 318 | 319 | * When declaring modules and classes, declare functions external to the table definition: 320 | 321 | ```lua 322 | local my_module = {} 323 | 324 | function my_module.a_function(x) 325 | -- code 326 | end 327 | ``` 328 | 329 | * When declaring metatables, declare function internal to the table definition. 330 | 331 | ```lua 332 | local version_mt = { 333 | __eq = function(a, b) 334 | -- code 335 | end, 336 | __lt = function(a, b) 337 | -- code 338 | end, 339 | } 340 | ``` 341 | 342 | > **Rationale:** Metatables contain special behavior that affect the tables 343 | they're assigned (and are used implicitly at the call site), so it's good to 344 | be able to get a view of the complete behavior of the metatable at a glance. 345 | 346 | This is not as important for objects and modules, which usually have way more 347 | code, and which don't fit in a single screen anyway, so nesting them inside 348 | the table does not gain much: when scrolling a longer file, it is more evident 349 | that `check_version` is a method of `Api` if it says `function Api:check_version()` 350 | than if it says `check_version = function()` under some indentation level. 351 | 352 | ## Variable declaration 353 | 354 | * Always use `local` to declare variables. 355 | 356 | ```lua 357 | -- bad 358 | superpower = get_superpower() 359 | 360 | -- good 361 | local superpower = get_superpower() 362 | ``` 363 | 364 | > **Rationale:** Not doing so will result in global variables to avoid polluting 365 | the global namespace. 366 | 367 | ## Variable scope 368 | 369 | * Assign variables with the smallest possible scope. 370 | 371 | ```lua 372 | -- bad 373 | local function good() 374 | local name = get_name() 375 | 376 | test() 377 | print("doing stuff..") 378 | 379 | --...other stuff... 380 | 381 | if name == "test" then 382 | return false 383 | end 384 | 385 | return name 386 | end 387 | 388 | -- good 389 | local bad = function() 390 | test() 391 | print("doing stuff..") 392 | 393 | --...other stuff... 394 | 395 | local name = get_name() 396 | 397 | if name == "test" then 398 | return false 399 | end 400 | 401 | return name 402 | end 403 | ``` 404 | 405 | > **Rationale:** Lua has proper lexical scoping. Declaring the function later means that its 406 | scope is smaller, so this makes it easier to check for the effects of a variable. 407 | 408 | ## Conditional expressions 409 | 410 | * False and nil are falsy in conditional expressions. Use shortcuts when you 411 | can, unless you need to know the difference between false and nil. 412 | 413 | ```lua 414 | -- bad 415 | if name ~= nil then 416 | -- ...stuff... 417 | end 418 | 419 | -- good 420 | if name then 421 | -- ...stuff... 422 | end 423 | ``` 424 | 425 | * Avoid designing APIs which depend on the difference between `nil` and `false`. 426 | 427 | * Use the `and`/`or` idiom for the pseudo-ternary operator when it results in 428 | more straightforward code. When nesting expressions, use parentheses to make it 429 | easier to scan visually: 430 | 431 | ```lua 432 | local function default_name(name) 433 | -- return the default "Waldo" if name is nil 434 | return name or "Waldo" 435 | end 436 | 437 | local function brew_coffee(machine) 438 | return (machine and machine.is_loaded) and "coffee brewing" or "fill your water" 439 | end 440 | ``` 441 | 442 | Note that the `x and y or z` as a substitute for `x ? y : z` does not work if 443 | `y` may be `nil` or `false` so avoid it altogether for returning booleans or 444 | values which may be nil. 445 | 446 | ## Blocks 447 | 448 | * Use single-line blocks only for `then return`, `then break` and `function return` (a.k.a "lambda") constructs: 449 | 450 | ```lua 451 | -- good 452 | if test then break end 453 | 454 | -- good 455 | if not ok then return nil, "this failed for this reason: " .. reason end 456 | 457 | -- good 458 | use_callback(x, function(k) return k.last end) 459 | 460 | -- good 461 | if test then 462 | return false 463 | end 464 | 465 | -- bad 466 | if test < 1 and do_complicated_function(test) == false or seven == 8 and nine == 10 then do_other_complicated_function() end 467 | 468 | -- good 469 | if test < 1 and do_complicated_function(test) == false or seven == 8 and nine == 10 then 470 | do_other_complicated_function() 471 | return false 472 | end 473 | ``` 474 | 475 | * Separate statements onto multiple lines. Do not use semicolons as statement terminators. 476 | 477 | ```lua 478 | -- bad 479 | local whatever = "sure"; 480 | a = 1; b = 2 481 | 482 | -- good 483 | local whatever = "sure" 484 | a = 1 485 | b = 2 486 | ``` 487 | 488 | ## Spacing 489 | 490 | * Use a space after `--`. 491 | 492 | ```lua 493 | --bad 494 | -- good 495 | ``` 496 | 497 | * Always put a space after commas and between operators and assignment signs: 498 | 499 | ```lua 500 | -- bad 501 | local x = y*9 502 | local numbers={1,2,3} 503 | numbers={1 , 2 , 3} 504 | numbers={1 ,2 ,3} 505 | local strings = { "hello" 506 | , "Lua" 507 | , "world" 508 | } 509 | dog.set( "attr",{ 510 | age="1 year", 511 | breed="Bernese Mountain Dog" 512 | }) 513 | 514 | -- good 515 | local x = y * 9 516 | local numbers = {1, 2, 3} 517 | local strings = { 518 | "hello", 519 | "Lua", 520 | "world", 521 | } 522 | dog.set("attr", { 523 | age = "1 year", 524 | breed = "Bernese Mountain Dog", 525 | }) 526 | ``` 527 | 528 | * Indent tables and functions according to the start of the line, not the construct: 529 | 530 | ```lua 531 | -- bad 532 | local my_table = { 533 | "hello", 534 | "world", 535 | } 536 | using_a_callback(x, function(...) 537 | print("hello") 538 | end) 539 | 540 | -- good 541 | local my_table = { 542 | "hello", 543 | "world", 544 | } 545 | using_a_callback(x, function(...) 546 | print("hello") 547 | end) 548 | ``` 549 | 550 | > **Rationale:** This keep indentation levels aligned at predictable places. You don't 551 | need to realign the entire block if something in the first line changes (such as 552 | replacing `x` with `xy` in the `using_a_callback` example above). 553 | 554 | * The concatenation operator gets a pass for avoiding spaces: 555 | 556 | ```lua 557 | -- okay 558 | local message = "Hello, "..user.."! This is your day # "..day.." in our platform!" 559 | ``` 560 | 561 | > **Rationale:** Being at the baseline, the dots already provide some visual spacing. 562 | 563 | * No spaces after the name of a function in a declaration or in its arguments: 564 | 565 | ```lua 566 | -- bad 567 | local function hello ( name, language ) 568 | -- code 569 | end 570 | 571 | -- good 572 | local function hello(name, language) 573 | -- code 574 | end 575 | ``` 576 | 577 | * Add blank lines between functions: 578 | 579 | ```lua 580 | -- bad 581 | local function foo() 582 | -- code 583 | end 584 | local function bar() 585 | -- code 586 | end 587 | 588 | -- good 589 | local function foo() 590 | -- code 591 | end 592 | 593 | local function bar() 594 | -- code 595 | end 596 | ``` 597 | 598 | * Avoid aligning variable declarations: 599 | 600 | ```lua 601 | -- bad 602 | local a = 1 603 | local long_identifier = 2 604 | 605 | -- good 606 | local a = 1 607 | local long_identifier = 2 608 | ``` 609 | 610 | > **Rationale:** This produces extra diffs which add noise to `git blame`. 611 | 612 | * Alignment is occasionally useful when logical correspondence is to be highlighted: 613 | 614 | ```lua 615 | -- okay 616 | sys_command(form, UI_FORM_UPDATE_NODE, "a", FORM_NODE_HIDDEN, false) 617 | sys_command(form, UI_FORM_UPDATE_NODE, "sample", FORM_NODE_VISIBLE, false) 618 | ``` 619 | 620 | ## Typing 621 | 622 | * In non-performance critical code, it can be useful to add type-checking assertions 623 | for function arguments: 624 | 625 | ```lua 626 | function manif.load_manifest(repo_url, lua_version) 627 | assert(type(repo_url) == "string") 628 | assert(type(lua_version) == "string" or not lua_version) 629 | 630 | -- ... 631 | end 632 | ``` 633 | 634 | > **Rationale:** This is a practice adopted early on in the development of LuaRocks 635 | that has shown to be beneficial in many occasions. 636 | 637 | * Use the standard functions for type conversion, avoid relying on coercion: 638 | 639 | ```lua 640 | -- bad 641 | local total_score = review_score .. "" 642 | 643 | -- good 644 | local total_score = tostring(review_score) 645 | ``` 646 | 647 | ## Errors 648 | 649 | * Functions that can fail for reasons that are expected (e.g. I/O) should 650 | return `nil` and a (string) error message on error, possibly followed by other 651 | return values such as an error code. 652 | 653 | * On errors such as API misuse, an error should be thrown, either with `error()` 654 | or `assert()`. 655 | 656 | ## Modules 657 | 658 | Follow [these guidelines](http://hisham.hm/2014/01/02/how-to-write-lua-modules-in-a-post-module-world/) for writing modules. In short: 659 | 660 | * Always require a module into a local variable named after the last component of the module’s full name. 661 | 662 | ```lua 663 | local bar = require("foo.bar") -- requiring the module 664 | 665 | bar.say("hello") -- using the module 666 | ``` 667 | 668 | * Don’t rename modules arbitrarily: 669 | 670 | ```lua 671 | -- bad 672 | local skt = require("socket") 673 | ``` 674 | 675 | > **Rationale:** Code is much harder to read if we have to keep going back to the top 676 | to check how you chose to call a module. 677 | 678 | * Start a module by declaring its table using the same all-lowercase local 679 | name that will be used to require it. You may use an LDoc comment to identify 680 | the whole module path. 681 | 682 | ```lua 683 | --- @module foo.bar 684 | local bar = {} 685 | ``` 686 | 687 | * Try to use names that won't clash with your local variables. For instance, don't 688 | name your module something like “size”. 689 | 690 | * Use `local function` to declare _local_ functions only: that is, functions 691 | that won’t be accessible from outside the module. 692 | 693 | That is, `local function helper_foo()` means that `helper_foo` is really local. 694 | 695 | * Public functions are declared in the module table, with dot syntax: 696 | 697 | ```lua 698 | function bar.say(greeting) 699 | print(greeting) 700 | end 701 | ``` 702 | 703 | > **Rationale:** Visibility rules are made explicit through syntax. 704 | 705 | * Do not set any globals in your module and always return a table in the end. 706 | 707 | * If you would like your module to be used as a function, you may set the 708 | `__call` metamethod on the module table instead. 709 | 710 | > **Rationale:** Modules should return tables in order to be amenable to have their 711 | contents inspected via the Lua interactive interpreter or other tools. 712 | 713 | * Requiring a module should cause no side-effect other than loading other 714 | modules and returning the module table. 715 | 716 | * A module should not have state (this still needs to be fixed for some 717 | LuaRocks modules). If a module needs configuration, turn it into a factory. 718 | For example, do not make something like this: 719 | 720 | ```lua 721 | -- bad 722 | local mp = require "MessagePack" 723 | mp.set_integer("unsigned") 724 | ``` 725 | 726 | and do something like this instead: 727 | 728 | ```lua 729 | -- good 730 | local messagepack = require("messagepack") 731 | local mpack = messagepack.new({integer = "unsigned"}) 732 | ``` 733 | 734 | * The invocation of require should look like a regular Lua function call, because it is. 735 | 736 | ```lua 737 | -- bad 738 | local bla = require "bla" 739 | 740 | -- good 741 | local bla = require("bla") 742 | ``` 743 | 744 | > **Rationale:** This makes it explicit that require is a function call and not a keyword. Many other languages employ keywords for this purpose, so having a "special syntax" for require would trip up Lua newcomers. 745 | 746 | ## OOP 747 | 748 | * Create classes like this: 749 | 750 | ```lua 751 | --- @module myproject.myclass 752 | local myclass = {} 753 | 754 | -- class table 755 | local MyClass = {} 756 | 757 | function MyClass:some_method() 758 | -- code 759 | end 760 | 761 | function MyClass:another_one() 762 | self:some_method() 763 | -- more code 764 | end 765 | 766 | function myclass.new() 767 | local self = {} 768 | setmetatable(self, { __index = MyClass }) 769 | return self 770 | end 771 | 772 | return myclass 773 | ``` 774 | 775 | * The class table and the class metatable should both be local. If containing 776 | metamethods, the metatable may be declared as a top-level local, named 777 | `MyClass_mt`. 778 | 779 | > **Rationale:** It’s easy to see in the code above that the functions with 780 | `MyClass` in their signature are methods. A deeper discussion of the 781 | design rationale for this is found [here](http://hisham.hm/2014/01/02/how-to-write-lua-modules-in-a-post-module-world/). 782 | 783 | * Use the method notation when invoking methods: 784 | 785 | ``` 786 | -- bad 787 | my_object.my_method(my_object) 788 | -- good 789 | my_object:my_method() 790 | ``` 791 | 792 | > **Rationale:** This makes it explicit that the intent is to use the function as an OOP method. 793 | 794 | * Do not rely on the `__gc` metamethod to release resources other than memory. 795 | If your object manage resources such as files, add a `close` method to their 796 | APIs and do not auto-close via `__gc`. Auto-closing via `__gc` would entice 797 | users of your module to not close resources as soon as possible. (Note that 798 | the standard `io` library does not follow this recommendation, and users often 799 | forget that not closing files immediately can lead to "too many open files" 800 | errors when the program runs for a while.) 801 | 802 | > **Rationale:** The garbage collector performs automatic *memory* management, 803 | dealing with memory only. There is no guarantees as to when the garbage 804 | collector will be invoked, and memory pressure does not correlate to pressure 805 | on other resources. 806 | 807 | ## File structure 808 | 809 | * Lua files should be named in all lowercase. 810 | 811 | * Lua files should be in a top-level `src` directory. The main library file 812 | should be called `modulename.lua`. 813 | 814 | * Tests should be in a top-level `spec` directory. LuaRocks uses 815 | [Busted](http://olivinelabs.com/busted/) for testing. 816 | 817 | * Executables are in `src/bin` directory. 818 | 819 | ## Static checking 820 | 821 | It's best if code passes [luacheck](https://github.com/mpeterv/luacheck). If 822 | it does not with default settings, it should provide a `.luacheckrc` with 823 | sensible exceptions. 824 | 825 | * luacheck warnings of class 6xx refer to whitespace issues and can be 826 | ignored. Do not send pull requests "fixing" trailing whitespaces. 827 | 828 | > **Rationale:** Git is paranoid about trailing whitespace due to the 829 | patch-file email-based workflow inherited from the Linux kernel mailing list. 830 | When using the Git tool proper, exceeding whitespace makes no difference 831 | whatsoever except for being highlighted by Git's coloring (for the aforementioned 832 | reasons). Git's pedantism about it has spread over the year to the syntax 833 | highlighting of many text editors and now everyone says they hate trailing 834 | whitespace without being really able to answer why (the actual cause being 835 | that tools complain to them about it, for no good reason). 836 | 837 | * luacheck warnings of class 211, 212, 213 (unused variable, argument or loop 838 | variable) should be ignored, if the unused variable was added explicitly: for 839 | example, sometimes it is useful, for code understandability, to spell out what 840 | the keys and values in a table are, even if you're only using one of them. 841 | Another example is a function that needs to follow a given signature for API 842 | reasons (e.g. a callback that follows a given format) but doesn't use some of 843 | its arguments; it's better to spell out in the argument what the API the 844 | function implements is, instead of adding `_` variables. 845 | 846 | * luacheck warning 542 (empty if branch) can also be ignored, when a sequence 847 | of `if`/`elseif`/`else` blocks implements a "switch/case"-style list of cases, 848 | and one of the cases is meant to mean "pass". For example: 849 | 850 | ```lua 851 | if warning >= 600 and warning <= 699 then 852 | print("no whitespace warnings") 853 | elseif warning == 542 then 854 | -- pass 855 | else 856 | print("got a warning: "..warning) 857 | end 858 | ``` 859 | 860 | > **Rationale:** This avoids writing negated conditions in the final fallback 861 | case, and it's easy to add another case to the construct without having to 862 | edit the fallback. 863 | 864 | --------------------------------------------------------------------------------