Help:Lua/Lua best practice/nb

Som enhver «beste praksis», så er denne Lua beste praksis tungt påvirket av enhver individuell bidragsyters mening om hva som bør være en god praksis. Bruk det du mener er viktig for ditt spesifikke prosjekt, men vit også at disse reglene har vist at de virker!

Eksemplene i det etterfølgende er for Lua, men de bør være enkle å reformulere for JavaScript, PHP, og Python. Grunnen for å gi eksempler for Lua er at modulene for dette språket er brukt mye, ofte av ikke-programmerere som ikke ser konsekvensene av sine valg.

Som et generelt råd så kan det være til stor hjelp å importere koden i et skikkelig programmeringsmiljø og sjekke det der for åpenbare feil og mangler. Flere frie alternativ eksisterer, blant dem Eclipse, TextMate, og Visual Studio Code for nevne noen få.

Spesielt, bruk et verktøy slik som lualint or luacheck. Det siste er noe bedre. Sjekk også om det er verktøy for deteksjon av rot og andre analyser tilgjengelig for ditt programmeringsmiljø.

Husk; konsisten stil er viktigere enn den «riktige» stilen – selv om det er stilen som du foretrekker!

Navn

 * Beskrivende navn
 * Velg beskrivende navn, unngå alt for generiske navn slik som  hvis ikke din kode virkelig er generisk. Ikke repeter en beskrivelse over flere nivåer, slik som et metodenavn som er satt til det samme som et klassenavn, hvis ikke metoden faktisk returnerer en klasse av den typen. Tenk fargerike ord, som er mer beskrivende ved større scope, men fjern unødige ord.


 * Kortnavn
 * Kryptiske kortnavn bør unngås. Skriv ut navnene, men vær konsistent. Ikke skriv, si isteden   eller  . Du kan ofte reformulere kortnavn og fortsatt gjøre dem korte, slik som   og.


 * Iteratornavn
 * Iteratorer har vanligvis kortnavn i Lua, og navnene har spesiell mening. Dette kan skape problemer hvis flere nøstede løkker skal bruke de samme navnene. En vanlig løsning er å legge til en ekstra del som prefiks eller suffiks til navnet, vanligvis fra flertallsformen brukt på samlingen, eller å bruke en entallsform av navnet på samlingen.


 * Navn med type
 * Lua har et ganske svakt typesystem, selv om det kan se sterkt ut på noen områder. Argumenter må enten bli tvunget til riktig type, eller så må funksjonen kaste en feilmelding. Hvis funksjonen finnes i spesielle utgaver for å håndtere forskjellige typer, så bør det være del av funksjonens navn.


 * Akronymer som navn
 * Akronymer er skremmende for de som ikke kjenner deres mening. Ikke bruk dem med mindre det er helt enkle og åpenbare tilfeller. I et bibliotek for å lage HTML-markup kan  være akseptabelt, men i et bibliotek for å lage infobokser kan det samme være uønsket.


 * Format for navn
 * Formatering av navn bør følge konvensjonen på det faktiske prosjektet. Lua bruker flere formateringsregler, men i Wikimedia virker det som UpperCamelCase for klassenavn, og lowerCamelCase for fuksjoner, metoder og variabelnavn. Modulnavn ser ut som de blir tolket som variabelnavn. Det er ikke noen klar praksis for konstanter, men UPPER_CASE_EMBEDDED_UNDERSCORE ser ut som et godt forslag.


 * Enkel understrek
 * I Lua-kode brukes en enkelt understreking som navn når et må angis, men ikke blir brukt. Dette er en placeholder som ellers blir ignorert. Dette respekteres av noen lintverktøy, og bør også respekteres i ordinær kode.


 * Innledende understrek
 * Ved konvensjon så brukes det en innledende understreking for navn som skal være private, men som av en eller annen grunn må være tilgjengelige fra utsiden. Variable med slike navn bør behandles som private uansett hva som har definert dem, hvis ikke de har en veldig klar forklaring som sier at du kan utføre spesifikke operasjoner på dem.

Formatering

 * Begrens linjelengde
 * Linjer bør begrenses til en rimelig lengde, typisk rundt 80 tegn. Årsaken er at lange linjer er vanskelige å lese, og når de blir lengre, så har de en tendens til å innkludere flere sammenblandede konsepter, og redigering av dem vil lett skape nye feil.


 * Innrykk av nye linjer
 * Programmerere har meninger om hvordan innrykk av nye linjer skal gjøres. Uansett hva slags mening du har, husk at dugnadsprosjekter bør følge noen felles standarder. Vær oppmerksom på at mens en tab ser ut som 4 mellomrom i online-editoren, vises den ikke slik i normal visning. Fordi nettverktøyet gjør innrykk på bestemte måter, bør du sette ditt programmeringsmiljø på samme måte.


 * Binære og linjebrekk
 * Sometimes it is necessary to put a line break inside an expression, typically an if-clause. This pose a special problem, as it opens up for copy-paste induced errors. To avoid problems a simple formatting tricks can be used, simply put the logical operator in front and the binary on a new line.
 * {| class="wikitable mw-collapsible mw-collapsed"

!colspan="2"|Example !Good !Bad
 * - valign="top"
 * }
 * Mellomrom
 * Whitespace is usually a GoodThing™, but people tend to disagree on how to use it. Done right it tends to increase readability of your code, but done wrong your code can be really hard to read. Find a style guide and stick to it. Or use a tool.
 * Mellomrom
 * Whitespace is usually a GoodThing™, but people tend to disagree on how to use it. Done right it tends to increase readability of your code, but done wrong your code can be really hard to read. Find a style guide and stick to it. Or use a tool.

Dokumentasjon

 * Grensesnittdokumentasjon
 * The interface is the exposed functions from the module, that is the functions you can invoke from the parser function. As a minimum document whatever arguments the interface function takes, and whatever value it returns. Only a single value is used from whatever the function returns. Remember to document if and how the metafunction  will transform the value.


 * Oversiktsdokumentasjon
 * The documentation should have an overview to give a general explanation of why and how the module, function, or variable is the way it is. This is not just the intended behaviour, it is why the behaviour is the way it is.


 * Annotering av parametre
 * Each parameter should be properly annotated. That is the expected type should be given and a short descriptive string. Write as if LDoc or a similar tool was available, usually as.


 * Annotering av retur
 * Each return value should be properly annotated. That is the expected type should be given and a short descriptive string. Write as if LDoc or a similar tool was available, usually as.

Kommentarer
Inline comments for the code itself.


 * Hvorfor-form på kommentarer
 * Comments are not for you who code some algorithm, they are for the one who reads your code. In the code path there should be answers to the how-questions, and in the comments there should be answers to the why-questions. Do not fall in the trap of replicating what you do in the code path in the comments, good comments provide new insight into the code.


 * Fortell din hensikt
 * State the intent of your code, in a clear and precise language. Do not just add a lot of words, think about the reader, what do she need to know to understand your code.


 * Refaktor utfra kommentarer
 * When the code has become to complex, it is common to start explaining the code for yourself. If you need your own comments, then something has gotten to involved and you should refactor the code.


 * Kommentarer om dårlige navn
 * A comment saying that a name is bad in some respect does not help. Do not comment on bad names, fix them!


 * «Todo» kommentarer
 * The marker todo is one of several common ones, and can be interpreted as "code the main programmer has not gotten around to fix yet". Usually you should write it as.


 * «Fixme» kommentarer
 * The marker fixme is one of several common ones, and can be interpreted as "code other than main programmer has identified as broken". Usually you should write it as . This is an invitation to other to try to fix the code.


 * «Hack» kommentarer
 * The marker hack is one of several common ones, and can be interpreted as "code other than main programmer has identified as broken and tried fixing in an unelegant way". Usually you should write it as . This is an invitation to other to try to fix the code.


 * «XXX» kommentar
 * The marker xxx is one of several common ones, and can be interpreted as "code identified as dangerously broken". Usually you should write it as . This marker should not be in production code, the code should be fixed asap.


 * Kommenter magiske tall
 * Constants and other magic numbers should have comments explaining why they have the specific content. Why is the line length set to 80 chars? Why is π truncated to 3.14?

Kode
Små mønstre og kodepraksis.


 * Programvaremønstre
 * A lot of work has gone into identifying common software design patterns, and developing good general solutions to those patterns. If you suspect you are attempting to do something that has a common pattern then do a search and check out how to implement the pattern. Still, know that patterns for languages with closures can be very different from those without closures. Usually Lua use tables to create objects, but can also use closures.


 * Sitattegn for strenger
 * In Lua there are several types of string quotes. Pick one of them and stick with it. If you need several types of quotes, either use your typical quote at the outermost level or at the innermost, and work your way out. Inside out with single quote as the primary quote and double quotes as secondary seems to be common, but could simply accidental. If more quotes are necessary, then start using double square brackets at the ternary level.


 * Tidlig retur
 * Returner så tidlig som mulig, spesielt hvis noe feiler. Vanligvis er programmerere fortalt at de skal bruke et enkelt returpunkt, men på grunn av språkkonstruksjonene i Lua så virker det som om dette skaper dypt nøstet kode. Det er derfor bedre å returnere tidlig.
 * {| class="wikitable mw-collapsible mw-collapsed"

!colspan="2"|Example !Good !Bad
 * - valign="top"
 * }
 * Unngå «else»
 * Alle betingelser kan bli skrevet slik at eksplisitte else-betingelser forsvinner. Alle av dem. Men noen ganger gjør else-betingelser at koden enklere å lese eller gjør at doble sett av if-betingelser kan unngås. I de tilfellene så er det akseptabelt å beholde, ellers bør den fjernes. Vær alltid mistenksom med else-betingelser.
 * Unngå «else»
 * Alle betingelser kan bli skrevet slik at eksplisitte else-betingelser forsvinner. Alle av dem. Men noen ganger gjør else-betingelser at koden enklere å lese eller gjør at doble sett av if-betingelser kan unngås. I de tilfellene så er det akseptabelt å beholde, ellers bør den fjernes. Vær alltid mistenksom med else-betingelser.


 * Sanne uttrykk først
 * Vanligvis er du fri til å ordne then- og else-betingelser slik det passer best, og da bør du organisere dem slik at if-betingelsen har en positiv test. Dette gjør at at koden blir enklere å lese. Hvis du kan unngå else-betingelsen så er det imidlertid viktigere.
 * {| class="wikitable mw-collapsible mw-collapsed"

!colspan="2"|Example !Good !Bad
 * - valign="top"
 * }
 * Spør først
 * Usually the interrogated value goes first in a logical expression, as this is more natural to read and thus less error prone. The inverted form is sometimes called the Yoda form. Sometimes (but rarely) the natural form does not work as expected, and the code terminates. This can be because Lua fails figure out a proper tail recursive form of the expression, and then the stack overflows.
 * {| class="wikitable mw-collapsible mw-collapsed"
 * Usually the interrogated value goes first in a logical expression, as this is more natural to read and thus less error prone. The inverted form is sometimes called the Yoda form. Sometimes (but rarely) the natural form does not work as expected, and the code terminates. This can be because Lua fails figure out a proper tail recursive form of the expression, and then the stack overflows.
 * {| class="wikitable mw-collapsible mw-collapsed"

!colspan="2"|Example !Good !Bad
 * - valign="top"
 * }
 * Angi standardverdi
 * In languages with an  operator like in Lua it is very easy to provide defaults. This is nice as some common constructs fails badly if given an uninitialized value. This happen for example when a table is unitialized and the code tries to index the nil value.
 * {| class="wikitable mw-collapsible mw-collapsed"
 * In languages with an  operator like in Lua it is very easy to provide defaults. This is nice as some common constructs fails badly if given an uninitialized value. This happen for example when a table is unitialized and the code tries to index the nil value.
 * {| class="wikitable mw-collapsible mw-collapsed"

!colspan="2"|Example !Good !Bad
 * - valign="top"
 * }
 * Binær betingelse
 * Lua does not have a binary conditional operator, but you can do the same anyhow with an . What goes on is although a little mysterious to newcomers to Lua. The   and   pass on truthy values, and thus they can be part of other expressions than just logical ones.
 * {| class="wikitable mw-collapsible mw-collapsed"
 * Lua does not have a binary conditional operator, but you can do the same anyhow with an . What goes on is although a little mysterious to newcomers to Lua. The   and   pass on truthy values, and thus they can be part of other expressions than just logical ones.
 * {| class="wikitable mw-collapsible mw-collapsed"

!colspan="2"|Example !Good !Bad
 * - valign="top"
 * }
 * Trinær betingelse
 * Lua does not have a ternary conditional operator, but you can do the same anyhow with an  and an  . What goes on is although a little mysterious to newcomers to Lua. The   and   pass on truthy values, and thus they can be part of other expressions than just logical ones.
 * {| class="wikitable mw-collapsible mw-collapsed"
 * Lua does not have a ternary conditional operator, but you can do the same anyhow with an  and an  . What goes on is although a little mysterious to newcomers to Lua. The   and   pass on truthy values, and thus they can be part of other expressions than just logical ones.
 * {| class="wikitable mw-collapsible mw-collapsed"

!colspan="2"|Example !Good !Bad
 * - valign="top"
 * }
 * Unngå repeat…until
 * The loop construct  delays the test until after the loop. This is error prone and should be avoided. The only times this is acceptable is when the test itself is costly compared to the executed block, or avoiding the repeat-clause would imply additional cleanup or finalize code.
 * Unngå repeat…until
 * The loop construct  delays the test until after the loop. This is error prone and should be avoided. The only times this is acceptable is when the test itself is costly compared to the executed block, or avoiding the repeat-clause would imply additional cleanup or finalize code.


 * Test argumenter
 * There is a small utility libraryUtil to test arguments types, and it should be used to avoid simple mistakes. Often the arguments are valid when other code is correct, but in fringe cases something creates a call outside the expected type range and the code fails in mysterious ways. Proper testing might catch an error early, and increase the probability of discovering the real root cause. Still note that type testing is a test for failure, and not a test for correctness.
 * {| class="wikitable mw-collapsible mw-collapsed"

!colspan="2"|Example !Good !Bad
 * - valign="top"
 * }
 * }
 * }

Mønstre
Noen få veldig vanlige programmeringsmønstre.


 * Kommandomønster
 * The single most common software pattern in Lua modules, that is most commonly missing, is the command pattern. Some data is available, and some action should be chosen given this data. A typical smell that a command pattern is missing is long chains of if-then-elseif-end tests. The most common variant does not have named commands, but an accept-qualifier function. Both versions are very common in parsing arguments from the "invoke" parser function.
 * {| class="wikitable mw-collapsible mw-collapsed"

!colspan="2"|Example
 * }
 * }
 * }
 * }
 * }

Testbarhet
Om testing og hvordan du gjør koden testbar. Vær oppmerksom på at den opprinnelige boken fra firergjengen har programmeringsmønstre for sterkt typede språk, som ikke passer svakt typede språk særlig godt. Hvorvidt Lua er sterkt typet, eller svakt, kan debatteres.


 * Kompleksitet
 * There are usually several execute paths through a given code, and this makes the code difficult to understand. The more code paths the more difficult the code become. This can be measured as cyclomatic complexity, and is a count of paths by counting branch points. This gives a fair, but not very good measure on code quality.


 * Unngå globale
 * Functions with globals are hard to test, no matter how the globals are included in the code. To avoid this accidental trap libraries can be included to wet the module, like . Still note that requiring some code is like importing a global, so be careful not to create a bigger problem.
 * {| class="wikitable mw-collapsible mw-collapsed"

!colspan="2"|Example !Good !Bad
 * - valign="top"
 * }
 * Unngå å endre scope
 * In Lua it is possible to check the scope of a function. Don't do that, as it will then depend on "mini-globals", which is nearly as bad as globals. If everything works as it should the mini-globals are probably semi-constant, but they might not.
 * Unngå å endre scope
 * In Lua it is possible to check the scope of a function. Don't do that, as it will then depend on "mini-globals", which is nearly as bad as globals. If everything works as it should the mini-globals are probably semi-constant, but they might not.

Se også

 * Lua referansemanual

Programmeringsmiljø
Noen råd om hvordan du konfigurerer ditt eksterne programmeringsmiljø.

Visual Studio Code
Bruk noe ala de følgende utvidelsene.
 * Lua
 * vscode-luacheck
 * Denne trenger en fil  med en enkelt linje , ellers vil den klage mye på den globale   variablen.
 * Lua snippets for Wikimedia

Andre verktøy
Dette er verktøy du kan finne nyttig.
 * GitHub: LuaDist/luametrics

Lesing

 * Kerievsky, Joshua; Refactoring to Patterns
 * Boswell, Dustin; Foucher, Trevor; The Art of Readable Code
 * Stefanov, Stoyan; JavaScript Patterns
 * Gamma, Erich; Helm, Richard; Johnson, Ralph; Vlissides, John; Design Patterns: Elements of Reusable Object-Oriented Software
 * Programming in Lua (5.0)
 * Lua 5.1 Reference Manual
 * LuaUsers: Sample Code
 * PEP 8 -- Style Guide for Python Code
 * LuaUsers: Lua Style Guide