Kode-stilguide

Denne vejledning indeholder oplysninger og retningslinjer for skrivning af kode til BeeWare.

Kodestil

BeeWare følger PEP 8 i vores kodebase, bortset fra at linjelængden er udvidet fra 79 til 88 tegn. Vi bruger Ruff til at håndhæve PEP 8-konventioner, hvor det er muligt. Når du committer din kode, kører pre-commit nogle kontroller, herunder Ruff. Hvor det er muligt, vil dette automatisk formatere din kode for at sikre, at den overholder vores formaterings- og stilstandarder. Du kan indstille nogle IDE'er til automatisk at køre Ruff ved gemning, hvilket kan hjælpe med processen.

Husk, at det vigtigste i PEP 8 er Afsnit 0: En tåbelig konsistens er små sinders mareridt. Der er situationer, hvor det ikke giver mening at være konsistent med PEP 8, og det er vigtigt at forstå, at det i visse tilfælde er acceptabelt og undertiden at foretrække at skrive kode, der ikke er i overensstemmelse med de anførte regler. At vide, hvornår man skal være inkonsekvent med disse regler, er lige så vigtigt som at opretholde konsistens i de fleste situationer.

Dette kommer blandt andet til udtryk i navngivningskonventionerne. BeeWare-biblioteker skal ofte fungere som bro til andre sprog. Når man udvikler wrappers til andre sprog, er det ønskeligt (og i nogle tilfælde nødvendigt) at følge målsprogets navngivningskonventioner frem for Pythons. Når man for eksempel kalder eller henviser til Java-kode, bør funktioner følge Javas præference for mixedCase, frem for PEP 8’s præference for snake_case.

Vi følger amerikansk stavning for API-navngivning, variabler osv.

Der er også nogle BeeWare-specifikke tilføjelser til PEP 8:

Opdeling af lange funktionskald

Når et funktionskald med mere end ét argument ikke kan være på én linje, skal hvert argument placeres på sin egen linje med et komma efter det sidste argument. Ruff tillader (og foreslår) et format med flere argumenter på én linje, der går over på næste linje:

my_function(
    arg1, arg2, arg3
)

Denne stil bør ikke anvendes. I stedet bør argumenterne fordeles med ét pr. linje ved at tilføje et komma efter det sidste argument:

my_function(
    arg1,
    arg2,
    arg3,
)

Opdeling af lange strenge

Når et strengargument skal deles op på flere linjer for at overholde kravene til linjelængde, skal du sætte de sammenkædede strengliteraler i parentes, så det fremgår tydeligt, at strengen udgør et enkelt argument. Det vil sige, at vi foretrækker:

my_function(
    (
        "this is a very long string "
        "that is wrapped over two lines"
    ),
    second_argument,
)

oversat til:

my_function(
    "this is a very long string "
    "that is wrapped over two lines",
    second_argument,
)

Ting, man bør undgå

Vi forsøger at undgå utils moduler så meget som muligt, men er klar over, at det nogle gange er uundgåeligt. Det foretrukne alternativ er at finde en anden placering for funktionen i kildekoden i stedet for at bruge et utils modul.

Som hovedregel forsøger vi at undgå eller udskyde dyr initialiseringskode for at opnå hurtigere opstart af appen. For eksempel er moduler i toga-core-pakken "lazy loaded" — de importeres kun, når der anmodes om det, i stedet for på forhånd. Dette fremskynder opstarten og bruger kun tid på det, appen faktisk bruger.