Review av Python Code

[norsemanGrey]

Jeg er relativt ny med Python og har nylig lagd min første lille "app". Det er et kommando-linje program for a bytte ut ord/tekt i en tekst file basert på en liste med ord i tekst filen som enten kan modifiseres med prefix/suffix eller/og bytte ut ordene med ordene i en annen liste.

 

https://github.com/SeaWolfX/Replaceroo

 

Jeg lurte på om noen med litt lenger erfaring med Python kunne tatt seg tiden til en liten "review" av koden som ligger på GitHub. Spesielt er jeg interessert i tilbakemelding på oppdelingen og bruk av funksjoner, struktureringen, og kommenteringen i koden.

 

I dist folderen ligger det en kjørbar .exe fil som jeg har generert ved hjelp av PyInstaller. Jeg kunne også tenkte med å gjøre strukturen slik at den kan installeres som en pakke og kjøres fra Python commando linje, men jeg er usikker på hvordan dette gjøres riktig, men bruk av main(), __init__, setup.py, osv. Det er mange kilder på nett som sier mye forskjellig rund dette og de fleste retter seg mot større programmer med flere filer. Setter stor pris på litt input på dette.

Endret 9. september 2018 av SeaWolf

[xaco]

Du presser for mye funksjonalitet inn i en funksjon. En funksjon burde gjør 1 ting og bare 1 ting, du har funksjoner der som er nesten 300 linjer lange og gjør 6-7 ting, splitt opp funksjonene dine.

 

Se også på do while løkker. Mange av while True løkkene dine burde vært byttet ut med de.

[etse]

En fin regel jeg lever etter er, om jeg føler jeg må ha kommentar i koden min er den ikke lesbar nok. Ofte er løsningen å ta funksjonaliteten jeg ville hatt en kommentar på ut i en egen funksjon med beskrivende navn.

 

Eksempler fra koden din:

# Save modified text to new file.
new_path = input_details.get("Source Text File").replace(".", "_mod.")
new_file = open(new_path, 'w', newline='\n')
new_file.write(modified_text)
new_file.close()

Her har du en kommentar jeg ville droppet. Kunne heller vært noe som:

 

def saveTextToFile(text, filename):
    with open(filename, 'w', newline='\n') as file: 
        file.write(modified_text)

outputFileName= input_details.get("Source Text File").replace(".", "_mod.")
saveTextToFile(modifiedText, outputFileName)

Lager man masse små funksjoner er de lette å forstå. (man klarer fint å forstå små funksjoner uten masse kommentarer så lenge de har beskrivende navn). Og når ting er lett å forstå trenger du ikke så masse kommentarer som bare tar opp plas - og etter du skriver om koden din er par ganger ofte ender opp med å lyve. (fordi man ofte endrer koden, men glemmer å rette kommentaren)

[Emsal]

og etter du skriver om koden din er par ganger ofte ender opp med å lyve. (fordi man ofte endrer koden, men glemmer å rette kommentaren)

Kan også fort skje at du endrer koden også passer ikke navnet til funksjonen med de nye tingen du har tenkt å bruke den til lenger. Så istedenfor å endre navnet alle steder fortsetter du å bruke samme navnet. Jeg er litt mer fan av et generelt navn og heller skrive kommentar (ikke at jeg er så superflink på det) og du trenger jo egentlig bare kommentar rett over deklarasjonen. Ikke for hver gang du bruker den.

[etse]

Kan også fort skje at du endrer koden også passer ikke navnet til funksjonen med de nye tingen du har tenkt å bruke den til lenger. Så istedenfor å endre navnet alle steder fortsetter du å bruke samme navnet. Jeg er litt mer fan av et generelt navn og heller skrive kommentar (ikke at jeg er så superflink på det) og du trenger jo egentlig bare kommentar rett over deklarasjonen. Ikke for hver gang du bruker den.

Må ærlig innrømme at veldig ofte dukker borti intetsigende eller helt feil kommentarer, men funksjonsnavn blir ofte endret på. Og her er de fleste av mine kolleger i hvertfall enige med meg. Gode funksjonsnavn > kommentarer. Men ja, det er mulig å skrive dårlig kode - men da vil neppe kommentarer redde deg.

 

Clean Code boka sier det også fint. Rett og slett, å føle du trenger en kommentar betyr koden ikke er lett å lese. Man burde alltid strebe etter å skrive lesbar kode. For for som oftest vil du lese 1000 linjer kode for hver linje du skriver. Og de få gangene du skriver en kommentar er det greit å tenke "why, not what". Altså hvorfor du gjør noe på den måten du gjør det - og ikke hva den gjør (det ser jeg jo av koden). F.eks. er det noen ganger du må gjøre noen rare designvalg p.g.a. et eller annet ikke helt intuitivt. Det er ofte greit å skrive en kommentar på.

[Emsal]

Altså jeg er enig at det er greiest å ha gode navn og skrive god kode. Hater å skrive kommentarer men ofte lager jeg mine egne biblioteker som jeg bruker senere. Da er det greit med dokumentasjon. Noen synes kanskje det er mer behagelig å lese tekst istedenfor kode.

 

En annen ting er at kunden ofte ikke vet hva de vil og vil ha det med en gang. Så hender ofte at man er blir ferdig med noe så vil kunden noe annet. Er lett å ta snarveier selv om man ikke burde.

 

Men selvfølgelig det er ikke noe som er diggere enn å kunne ta seg god tid å skrive god kode. Men da har jeg gjerne i tillegg til beskrivende navn også kommentarer. Om ikke hvilke parametere som forventes men også hva som kommer ut.

 

Ta f.eks en funksjon som formaterer et tall. Forventer den heltall, desimaler, hva får jeg ut hvis den feiler. Er greier å lese i kommentaren, "returns false on fail" enn å f.eks lese flere linjer med kode.

 

Nå programmerer ikke jeg i python så kan hende ting er mer opplagt.

[xaco]

Altså jeg er enig at det er greiest å ha gode navn og skrive god kode. Hater å skrive kommentarer men ofte lager jeg mine egne biblioteker som jeg bruker senere. Da er det greit med dokumentasjon. Noen synes kanskje det er mer behagelig å lese tekst istedenfor kode.

 

En annen ting er at kunden ofte ikke vet hva de vil og vil ha det med en gang. Så hender ofte at man er blir ferdig med noe så vil kunden noe annet. Er lett å ta snarveier selv om man ikke burde.

 

Men selvfølgelig det er ikke noe som er diggere enn å kunne ta seg god tid å skrive god kode. Men da har jeg gjerne i tillegg til beskrivende navn også kommentarer. Om ikke hvilke parametere som forventes men også hva som kommer ut.

 

Ta f.eks en funksjon som formaterer et tall. Forventer den heltall, desimaler, hva får jeg ut hvis den feiler. Er greier å lese i kommentaren, "returns false on fail" enn å f.eks lese flere linjer med kode.

 

Nå programmerer ikke jeg i python så kan hende ting er mer opplagt.

 

Det er forskjell på å dokumentere metodene i et api/metodene i et rammeverk, hvor man gjerne generer noen fine nettsider ut av etc. og kommentarer i vanlig kode. Her er det veldig mye kommentarer i koden.

Endret 11. september 2018 av xaco

[n0mad]

Det er mye bedre aa splitte ut ting i egne funksjoner, som kun gjoer en ting. En annen fordel er at du da lettere kan se hvor ting feiler, og du har muligheten til aa gjoere retry paa kun en ting, f.eks. dersom et API-kall feiler, kan du proeve igjen opp til 3 ganger.

 

En annen stor fordel er at du kan gjenbruke kode. F.eks. har jeg en del sider laget i Flask, hvor jeg har en klikk-validerings-funksjon som sjekker HTTP-headers, som jeg bruker flere steder, samt funksjoner for aa sjekke innhold (readability score mm). 

 

For funksjoner som ikke er like greie aa lese, f.eks. funksjoner som henter data fra eksterne API-kilder, legger jeg inn kommentarer, men ellers bruker jeg kun en Readme-fil. Jeg kommenterer ogsaa i kode for modeller for database (SQLAlchemy) og i klasser.