LISÄSIVUT 1 PYTHON-TYYLISÄÄNNÖISTÄ. Lappeenrannan teknillinen yliopisto 2007 Jussi Kasurinen

Transkriptio

1 LISÄSIVUT 1 PYTHON-TYYLISÄÄNNÖISTÄ Lappeenrannan teknillinen yliopisto 2007 Jussi Kasurinen

2 Python-tyylisäännöistä Alkuperäinen lähde Python Enhancement Proposal 8, Johdanto Tämä asiakirja määrittelee Python-ohjelmointikielelle tyylin, jolla Python-ohjelmointiympäristön mukana toimitettavan perus-moduulikirjaston funktiolle saadaan yhtenäinen ja helposti ymmärrettävissä oleva esitystapa. Tätä tyylisäännöstöä voidaan soveltaa myös lisämoduuleihin, kuten py2exe- tai numpy-moduuliin, mutta niiden kanssa voidaan joutua tekemään joitakin kompromisseja. Asiakirja on vapaasti suomennettu ja koottu alkuperäisestä Python Enhancement Proposalista numero 8. Kyseinen PEP sisältää Guido van Rossumin ja Barry Warsawin tyylioppaista kootun kokonaisuuden, jolla määritellään kielen virallinen tyyliopas. Perusajatus Guido van Rossumin alkuperäinen ajatus ohjelmoinnista on, että ihmiset käyttävät enemmän aikaa koodin tulkitsemiseen kuin sen kirjoittamiseen. Tämän vuoksi Python-ohjelmoinnissa ja ohjelmointityylissä pyritään aina suosimaan kielen ymmärrettävyyttä sekä pitämään lähdekoodin kieliasu yhtenäisenä. Kannattaa kuitenkin pitää mielessä, että joskus on olemassa tilanteita, joihin tietyt tyylisäännöt tai tyylioppaat eivät vain yksinkertaisesti päde. Tällöin tulee kuitenkin pyrkiä pitämään linja yhtenäisenä, ja huolehtia siitä, että Python-koodin tärkein ominaisuus sen ymmärrettävyys ja selkeys pysyy edelleen prioriteettina. 1

3 Tyylisäännöt Sisennyksestä Käytä sisennyksissä koodin tasolta toiselle aina neljää (4) välilyöntiä per taso. Ainoan poikkeuksen tähän tekee erittäin vanhojen lähdekoodien, jotka käyttävät aiemmin voimassa ollutta 8 välilyönnin standardia, ylläpito ja korjaus. Älä koskaan käytä yhtäaikaisesti sisennysmerkkejä ja välilyöntejä. Mikäli et ole varma tallentaako käyttämäsi editoriohjelma sisennysmerkit automaattisesti neljänä välilyöntinä, älä käytä molempia vaan ainoastaan toista merkkiä sisennyksen tekemiseen. Rivien pituudesta ja monirivisistä lauseista Pidä lähdekoodin yhden koodirivin pituus maksimissaan 80 merkkiä pitkänä. Edelleen on olemassa laitteita, joiden näyttökyky rajoittuu 80 merkkiin per rivi; lisäksi pidättäytymällä tässä säännössä on helpompaa tarkastella kahta koodia yhtä aikaa yhdeltä näytöltä. Lisäksi, mikäli kirjoitat funktioillesi dokumentaatiorivejä, käytä näiden tapauksessa rivin pituutena 72 merkkiä. Käytä rivien katkaisemiseen Python-tulkin kenoviivaa ( \ ). Jos välttämättä tarvitset, voit käyttää myös sulkeita, mutta useimmiten kenoviiva näyttää paremmalta. Lisäksi katkaisun jälkeinen rivi on sisennettävä oikealle tasolleen joko alkuperäisen rivin tasalle tai sulkeiden alkamistasolle. Esimerkkejä: class Rectangle(Blob): def init (self, width, height, color='black', emphasis=none, highlight=0): if width == 0 and height == 0 and \ color == 'red' and emphasis == 'strong' or \ highlight > 100: raise ValueError("sorry, you lose") if width == 0 and height == 0 and (color == 'red' or emphasis is None): raise ValueError("I don't think so") Blob. init (self, width, height, color, emphasis, highlight) 2

4 Tyhjistä riveistä Erota määritellyt funktiot ja dynaamiset rakenteet tosistaan vähintään kahdella tyhjällä rivillä. Erottele lisäksi määritellyt funktiot muusta koodista tyhjällä rivillä ennen funktiota ja funktion jälkeen. Lisäksi tyhjiä rivejä voidaan lisätä, mikäli tarkoituksena on erotella koodista toisiinsa liittyvät funktiot. Funktion sisällä tyhjiä rivejä voidaan käyttää erottelemaan koodin loogiset osat toisistaan. Koodisivun valinnasta Mikäli mahdollista, käytä aina pelkkää standardi-ascii-merkistöä. Mikäli tarvitset laajennettua ASCII-merkistöä, käytä koodisivuna joko merkistöjä Latin-1, UTF-8 tai cp1252. Mikäli tarvitset ainoastaan yksittäisiä merkkejä, on suotavampaa käyttää \x, \u tai \U notaatioa koodisivun vaihtamisen sijaan. Sisällyttämisestä Kokonaisten moduulien sisällyttäminen tulee aina toteuttaa erillisillä riveillä: Oikein: import os import sys Väärin: import sys, os Mikäli kuitenkin sisällytät ainoastaan osia moduulista, voidaan käyttää merkintätapaa from subprocess import Popen, PIPE Sisällytyskäskyt tulee aina sijoittaa lähdekoodin alkuun. Ainoastaan koodisivun valinta ja lähdekoodin header-kommentit tulee ennen sisällyttämiskäskyjä. Lisäksi sisällyttämisessä tulisi käyttää seuraavaa järjestystä: 1. Standardikirjastosta sisällytettävät moduulit (sys,os, time ) 2. Lisämoduuleista sisällytettävät moduulit (py2exe, image, numpy ) 3. Paikalliset lähdekooditiedostot (omat ulkopuoliset lähdekooditiedostot) Ryhmät tulee erotella toisistaan tyhjällä rivillä. Kokonaisen moduulin sisällyttämisessä tulee aina pyrkiä käyttämään täydellä nimellä sisällyttämistä (import X). Mikäli sisällytät ainoastaan yksittäisiä funktioita, voit käyttää notaatiota (from X import Y). 3

5 Välilyönneistä Välilyöntien käyttäminen koodin luettavuuden parantamiseksi on hyvä käytäntö, mutta siihen liittyy muutamia sääntöjä, joilla haluttua vaikutusta voidaan tehostaa. Älä käytä välilyöntiä seuraavissa kohdissa: - Välittömästi kaarisulkeiden, hakasulkeiden tai aaltosulkeiden perään. Oikein: spam(ham[1], {eggs: 2}) Väärin: spam( ham[ 1 ], { eggs: 2 } ) -Ennen pilkkua, kaksoispistettä tai puolipistettä: Oikein: if x == 4: print x, y; x, y = y, x Väärin: if x == 4 : print x, y ; x, y = y, x Ennen sulkeita, jotka aloittavat funktiokutsun parametrilistan: Oikein: spam(1) Väärin: spam (1) Ennen sulkeita, jotka määrittelevät leikkauksen tai alkioviittauksen: Oikein: dict['key'] = list[index] Väärin: dict ['key'] = list [index] Enemmän kuin yksi välilyönti viittausten tai sijoitusten ympärillä: Oikein: Väärin: x = 1 y = 2 pitka_nimi = 3 x = 1 y = 2 pitka_nimi = 3 4

6 Käytä välilyöntiä seuraavissa kohdissa: Erottele seuraavat merkit ja vertausoperaatiot aina molemmin puolin välilyönneillä: sijoitus (=), arvoa muuttava sijoitus (+=, -= etc.), vertailut (==, <, >,!=, <>, <=, >=, in, not in, is, is not), Boolean-arvot (and, or, not). Erottele numeroarvot ja muuttajat operaattoreista: Oikein: Väärin: i = i + 1 vastaanotettu += 1 x = x * 2-1 hypot2 = x * x + y * y c = (a + b) * (a - b) i=i+1 vastaanotettu +=1 x = x*2-1 hypot2 = x*x + y*y c = (a+b) * (a-b) Ainoa poikkeus tähän on parametrien avainsanat, joihin välilyöntejä ei tarvitse laittaa: Oikein: def complex(real, imag=0.0): return magic(r=real, i=imag) Ei niin oikein: def complex(real, imag = 0.0): return magic(r = real, i = imag) 5

7 Rivityksestä Usean loogisen lauseen rivittämistä samalle fyysiselle riville tulisi välttää. Oikein: if foo == 'blah': do_blah_thing() do_one() do_two() do_three() Ei niin oikein: if foo == 'blah': do_blah_thing() do_one(); do_two(); do_three() Vaikka joskus yksinkertaisen if-,for-, tai while rakenteen sijoittaminen samalle riville vaikuttaisi hyvältä, tulisi sitä siitäkin huolimatta välttää. Jos rakenteessa on enemmän kuin yksi osio, osiossa enemmän kuin yksi rivi tai rivi pitäisi pituuden vuoksi katkaista epäloogisesta kohdasta, tulee rakenne ehdottomasti sijoittaa fyysesti eri riveille: Mielellään ei: if foo == 'blah': jotain() for x in lst: total += x while t < 10: t = laske() Ehdottomasti ei: if foo == 'blah': tee_jotain() else: jotain_muuta() try: jotain() finally: muuta() yksi(); kaksi(); kolme(pitka, lista, argu, mentteja) if foo == 'blaah': yksi(); kaksi(); kolme() 6

8 Kommentoinnista Yleisesti Kommentit, jotka eivät pidä yhtä koodin toiminnan kanssa ovat suurempi ongelma kuin puutteellinen kommentointi. Huolehdi siitä, että kommentit ovat jatkuvasti ajan tasalla. Kommenttien tulisi olla kokonaisia lauseita. Kirjoita kommenttisi siten, että ne alkavat isolla alkukirjaimella ja päättyvät pisteeseen. Ainoan poikkeuksen tähän tekee se, jos kommentti alkaa muuttujan tai funktion nimellä, joka koodissa kirjoitetaan pienellä; tällöin myös kommentti alkaa pienellä kirjaimella. Jos kommentti on muutaman sanan pituinen, voidaan lauserakenteesta tinkiä. Jos kirjoitat pitkän kommenttitekstin, kirjoita teksti kieliopillisesti oikein. Pyri välttämään lyhenteitä. Kirjoita kommentointi aina englanniksi, mikäli on pienikin todennäköisyys, että koodisi voi päätyä julkisesti saataville ja mikäli sinua ei ole erikseen ohjeistettu tekemään toisin. Koodiosion kommentointi Jos kirjoitat koko koodiosiota koskevan kommentoinnin, sisennetään se samalle tasolle millä koodiosio on. Monirivisessä kommentoinnissa käytä menetelmää, jossa # -merkin jälkeen tulee ainakin yksi välilyönti. Kappaleenvaihto monirivisessä kommentissa merkitään tyhjällä kommenttirivillä, jolla on ainoastaan # -merkki. Koodinsisäinen kommentointi Koodinsisäinen kommentointi tarkoittaa kommentteja, jotka kirjoitetaan koodirivin perään. Koodinsisäinen kommentti erotetaan koodirivistä vähintään kahdella välilyönnillä. Lisäksi koodinsisäiset kommentit häiritsevät koodin lukemista, joten niitä ei tulisi käyttää kuvaamaan itsestään selviä asioita. Esimerkiksi kommentti x = x + 1 # x kasvaa yhdella on turha ja haittaa koodin luettavuutta. Sen sijaan kommentti x = x + 1 # lisataan listan ylarajaa yhdella on tietyissä tapauksissa hyödyllistä tietoa. 7

9 Dokumenttiriveistä Kirjoita dokumenttirivi jokaiselle julkiselle moduulille, funktiolle sekä rakenteelle jonka luot. Jos tekemäsi funktio ei ole julkinen, vaan on tarkoitettu moduulinsisäiseen käyttöön, ei siihen tarvita dokumenttiriviä. Dokumenttirivi tulee välittömästi osion alkuun, heti def-määritelmän jälkeen. Kirjoita dokumenttirivi käyttäen kolmen sitaattimerkin notaatiota. Huomio lisäksi, että monirivisessä dokumentaatiossa sulkevat sitaattimerkit tulevat omalle rivilleen. Muista myös, että dokumenttirivien maksimipituus olisi hyvä rajoittaa 73:een merkkiin. Oikein: """Return a foobang Optional plotz says to frobnicate the bizbaz first. Accepted types: plotz - integer frobnicate string bizbaz list """ """For one liner docstrings, it's okay to keep the closing on the same line. """ Versionumeroinnista Jos koodiprojektissasi toteutetaan versionumeron seurantaa CVS, RCS tai Subversion menetelmillä, merkitse koodisi versionumero seuraavalla notaatiolla. version = "$Revision: xxxxx $" # $Source$ Versionumero yleisesti tulee sijoittaa moduulin dokumenttiriville ennen varsinaisia koodirivejä erotettuna ylä- ja alapuoleltaan tyhjällä rivillä. 8

10 Nimeämiskäytännöistä Vaikka alkuperäinen nimeämiskäytäntö Pythonin moduulikirjastoissa on välillä hieman sekava, on silti tarkoituksena jatkossa pyrkiä nimeämään funktioiden ja muuttujien nimet siten, että ne noudattavat tiettyä kaavaa. Nimeämislogiikasta Käytä muuttujien, funktioiden ja rakenteiden nimeämiseen menetelmää, joka kuuluu johonkin seuraavista kategorioista: - b (yksittäinen pieni kirjain) - B (yksittäinen iso kirjain) - muuttujannimi (pelkkiä pieniä kirjaimia) - muuttujan_nimi_viivalla_erotettuna - MUUTTUJANNIMI (pelkkiä isoja kirjaimia) - MUUTTUJAN_NIMI_VIIVALLA_EROTETTUNA - IsotKirjaimet (muuttujan nimen sanat alkavat isolla kirjaimella) Huomioi tämä: Jos käytät tätä nimeämislogiikkaa, niin käytä isoja kirjaimia myös lyhenteissä: HTTPServerError on parempi kuin HttpServerError. - pienialkukirjain (sama kuin yllä, mutta alkaa pienellä kirjaimella) - Isot_Alkukirjaimet_Viivalla_Erotettuna - _aloittava_alaviiva (plus muut kombinaatiot) Nimiä, joita tulisi välttää Pyri välttämään seuraavia merkkejä muuttujannimissä: - l : pieni L - O : iso o - I, iso i Nämä merkit voidaan joillain fonttityypeillä helposti sekoittaa numeroarvoihin 1 ja 0. Kokonaisina muuttujanniminä olisi suositeltavampaa olla kokonaan käyttämättä kyseisiä kirjaimia (esimerkiksi pientä L-kirjainta toistorakenteen askeltajana). 9

11 Moduulien, muuttujien ja funktioiden nimistä Moduuleilla tulisi olla lyhyt, kokonaan pienillä kirjaimilla kirjoitettu, nimi. Myös alaviivaa voidaan käyttää mikäli sillä voidaan parantaa nimen luettavuutta. Koska tulkki hakee moduuleja niiden tiedostonnimistä, olisi moduulin nimen silloin syytä olla erittäin lyhyt ja yksinkertainen. Mikäli voidaan olettaa, että koodia voidaan käyttää vanhoissa Mac- tai DOS-koneissa, on nimen hyvä olla maksimissaan 7 merkkiä pitkä. Samoin alaviivan käyttöä kannattaa näissä tapauksissa välttää. Rakenteisten tietotyyppien tai luokkien nimissä tulisi käyttää IsotKirjaimet-nimeämislogiikkaa. Jos rakenne tulee vain moduulinsisäiseen käyttöön, voidaan myös aloittavaa alaviivaa käyttää. Itse määritellyissä virhetilanteissa virheen nimen tulisi olla IsotKirjaimet-tyylinen, sekä sisältää päätteenä sana Error. Funktioiden nimien tulisi olla kirjoitettu kokonaan pienillä kirjaimilla. Lisäksi niiden kanssa voi käyttää alaviivaa, mikäli se parantaa nimen ymmärrettävyyttä. Valmiiiden globaalien muuttujien nimeämiskäytäntö nimi (kaksoisalaviiva) on varattu järjestelmän itsensä luomille muuttujannimille. Älä käytä näitä ellet oikeasti tiedä mitä olet tekemässä ja olet varma, että ylikirjoitusvaaraa ei ole olemassa. Mikäli haluamasi muuttujannimi on järjestelmän varattu sana (esimerkiksi except tai print ), on parempi menetelmä jättää muuttujannimestä kirjain pois ( xcept, prnt ) kuin lisätä alaviiva ( except_, _print ). Tietenkin paras tapa on olla käyttämättä varattujen sanojen kaltaisia muuttujannimiä. Edistyneemmistä ohjelmointitavoista Pyri välttämään ohjelmoinnissa kirjoitustapoja, jotka haittaavat merkittävästi muiden ei-cpythonpohjaisten menetelmien käyttämistä. (Esimerkiksi PyPy, Jython, IronPython, Pyrex, Psyco jne...) Vertailuoperaattorit perusarvoihin, kuten None, True tai False, tulisi aina tehdä operaattorilla is tai is not, ei yhtäsuuruusoperaattoreilla ( == tai!= ) Huomaa myös, että if x ei välttämättä tarkoita if x is not None, koska x:n arvoksi on voitu asettaa jotain (kuten säiliö), jonka arvo Boolean-vertailussa on False. 10

12 Virheiden ja poikkeuksien käsittelystä Jos kirjoitat poikkeuksia, tee niistä luokkia. Näiden luokkien tulisi olla Exception-luokasta perittyjä. Lisäksi kirjoita näille luokille aina dokumenttirivit. Kutsu poikkeuksia aina syntaksilla raise ValueError('viesti') Poikkeuksien kiinniottamisessa tulisi aina käyttää spesifistä except-arvoa jolla määritellään mitä virheitä koitetaan ottaa kiinni. Oikein: try: import platform_specific_module except ImportError: platform_specific_module = None Väärin: try: import platform_specific_module except: platform_specific_module = None Pelkkä except rikkoo SystemExit- ja KeyboardInterrupt-poikkeukset, jolloin käyttäjä ei pysty kontrolloimaan ohjelman keskeyttämistä. Jos haluat käyttää yleistermiä, jolla saat kaikki oikeat virheet kiinni, käytä exceptissä notaatiota 'except StandardError:'. Kaikkien poikkeusten kiinniottoa voidaan käyttää ainoastaan kahdessa tapauksessa: - Jos käsin määritelty poikkeuksenkäsittelijä tulostaa virheilmoituksen, eli käyttäjä tietää jotain menneen pieleen. - Jos koodin on tarve siivota jälkiään virheen sattumisen ja lopettamisen välillä. Tällöinkin on suositeltavampaa käyttää try-finally-rakennetta. Lisäksi on hyvä käytännön mukaista sisällyttää try-osioon ainoastaan se osa koodista, joka voi aiheuttaa virheen jolle except-osiossa on määritelty käsittelijä. Jos palautamme jotain, voimme toteuttaa sen else-osiolla. Oikein: Väärin: try: value = collection[key] except KeyError: return key_not_found(key) else: return handle_value(value) try: value = collection[key] return handle_value(collection[key]) except KeyError: # Ottaisi kiinni myös handle_value-funktion KeyErrorin return key_not_found(key) 11

13 Loogisista väittämistä ja arvojen testauksesta Käytä merkkijonojen kanssa aina valmiita muokkausmetodeja. Älä kutsu käsin string-moduulia. Ainoan poikkeuksen tähän tekee koodit, joissa tarvitaan yhteensopivuutta aiempien (Python 2.0 vanhempien) tulkin versioiden kanssa. Merkkijonon alku- ja loppupään arvojen testauksessa tulisi käyttää ennemmin.startswith() ja.endswith() metodeja kuin leikkausten vertailua. Tämä parantaa koodin luettavuutta ja on vähemmän virheherkkä tapa ilmaista sama asia. Oikein: if foo.startswith('bar'): Väärin: if foo[:3] == 'bar': Objektien tyyppien vertailussa tulisi käyttää isinstance()-funktiota suoran vertailun sijaan. Oikein: if isinstance(obj, int): Väärin: if type(obj) is type(1): Jos koodissasi käytetään Unicode-merkkijonoja, joudut tekemään testin seuraavalla tavalla jotta saat oikean vastauksen riippumatta siitä, onko kyseessä normaali- vai unicode-merkkijono: if isinstance(obj, basestring): Sarjallisten muuttujien (merkkijonot, listat, tuplet) testauksessa tulisi hyödyntää sitä tosiseikkaa, että tyhjä sarjallinen muuttuja palauttaa arvon False Oikein: if not seq: if seq: Väärin: if len(seq) if not len(seq) Älä käytä merkkijonojen lopussa välilyöntejä merkkijonon pituuden säännöstelyyn. Kyseinen merkintätapa on visuaalisesti näkymätön eikä sen olemassaoloa huomaa ellei siitä tiedä. Lisäksi jotkin editointiohjelmat poistaa lopusta välilyöntejä sotkien käyttämäsi menetelmän. Älä vertaile Boolean-arvoja käyttäen yhtäsuuruusoperaattoria. Oikein: if greeting: Väärin: if greeting == True: Väärin: if greeting is True: Kun olet tottunut if- ja while-rakenteen kanssa työskentelyyn, olisi hyvä lopettaa Boolean-arvojen toistaminen koodissa. 12

14 Muista tyyliseikoista Lisäsivut Kuten mainittu, on Pythonin ajatus olla nimenomaisesti ohjelmointikieli, jonka lähdekoodia on helppoa tulkita ja ymmärtää. Noudata aina yhdenmukaista ja selkeää esitystapaa. Jos tulet tilanteeseen, johon näissä ohjeissa ei otettu kantaa, on sinun hyvä hetken aikaa miettiä Pythonohjelmoinnin zeniläistä ajatusta, joka on Tim Petersin [1] kehittelemä: The Zen of Python Beautiful is better than ugly. Explicit is better than implicit. Simple is better than complex. Complex is better than complicated. Flat is better than nested. Sparse is better than dense. Readability counts. Special cases aren't special enough to break the rules. Although practicality beats purity. Errors should never pass silently. Unless explicitly silenced. In the face of ambiguity, refuse the temptation to guess. There should be one-- and preferably only one --obvious way to do it. Although that way may not be obvious at first unless you're Dutch. Now is better than never. Although never is often better than *right* now. If the implementation is hard to explain, it's a bad idea. If the implementation is easy to explain, it may be a good idea. Namespaces are one honking great idea -- let's do more of those! Näitä mietelauseita kannattaa ajatella kun suunnittelet omaa ohjelmointityyliäsi. Nämä mietelauseet löytyvät myös Python-tulkistasi; kirjoita tulkin interaktiiviseen ikkunaan import this ja kokeile itse. Tärkeintä onkin, että koodaatpa miten tahansa, niin huolehdi että olet johdonmukainen, kommentoit koodisi hyvin ja noudatat itsestäsi luontevimmalta tuntuvaa tapaa. [1] Peters, Tim (2004) Python Enhancement Proposal 20: The Zen of Python. Saatavilla osoitteesta Copyright Kannen kuva: Nila Gurusinghe. Kuva julkaistu Creative Commons - Nimi mainittava lisenssillä. Tähän asiakirjaan sovelletaan Creative Commonsin Vapaa Yleinen Käyttö (Public Domain) lisenssiä. Lappeenrannan teknillinen yliopisto