A R Programazio Estilo-Gida

Liburuan zehar hainbat adibide daude metaheuristikoen erabilera eta inplementazioa erakusteko; adibide hauek R lengoaian daude inplementatuta. Lengoaia interpretatu bat aukeratzearen arrazoia ondorengoa da: Liburuko kodea oinarritzat hartuta, probak egitea erraza izan dadin. Alabaina, liburuko kodea ulergaitza balitz, nekez lortuko genuke gure helburua.

Kodearen ulergarritasuna hobetzearren programazioan estilo-gidak erabili ohi dira. Askotan, horrelako gidak lengoaia garatzen duen taldeak berak idazten ditu, baina R ren kasuan ez da horrela; Hare gehiago, ez dago ezta ere de factokoa den estilorik. Dena dela, horrek ez du esan nahi R programazio estilo-gidarik ez dagoenik. Liburu honetan jarraituko ditugun irizpideak (gehienak, behintzat) hainbat gidetatik ateratakoak dira. Bereziki, azpian aipatzen ditugun gidetan oinarritu gara hemen proposatutako estiloa sortzeko:

  • Google’s R style guide.11 Googlek eragin handiko hainbat estilo-gida sortu ditu eta, arlo honetan, erreferente nagusienetariko bat da.
  • Hadley Wickham’s guide.12 H. Wickhamek ggplot2 paketea garatu zuen eta gaur egun RStudio konpainian dihardu. Haren gida Advanced R liburuan aurki daiteke.
  • Bioconductor’s coding style.13 Aurreko eranskinean ikusi dugun bezala, Bioconductor R pakete-biltegi nagusienetariko bat da.

Goian apiatutako gidak ez ezik, beste hainbat dokumentu ere erabili ditugu gure estilo-gida definitzeko, hala nola, C. Guillespies’s guide14, Bernd Bischi’ guide15, G. William’s style16, Genolini’s introduction to S4 (Genolini 2009), P.E. Johnson’s analysis (Johnson 2015) and R. Bååth’s paper on naming conventions (Bååth 2012).

A.1 Izenak

Estilo-giden artean, aldagaien eta funtzioen izenak sortzeko arauak dira, ziurrenik, heterogenidade handien dutenak. Gai honi buruz oso artikulu interesgarri bat aurki daiteke The R Journal aldizkarian (Bååth 2012). Artikulu honek gehien erabiltzen diren estrategiak laburbiltzen ditu eta, ondoren, CRAN biltegian dauden paketeak aztertzen ditu, estrategia bakoitzaren erabilera erakusteko.

Googleko gidak dio, aldagaien izenei dagokienez, letra xeheak erabili behar direla eta hitzak puntu ikurra erabiliz banandu behar direla –adibidez, aldagaiaren.izena–. Gidak formatu hura lehenetsi arren, hitzak letra larriz banatzea ere onartzen dela dio –alegia, aldagaiarenIzena–.

Funtzioen kasuan, berriz, puntuak ez erabiltzeko dio gidak; Hitzak letra larriak erabiliz banatu behar dira, lehenengo letra, kasu honetan, larria izanik –esate baterako, NireFuntzioa–.

Wickham-ek aldagaien zein funtzioen kasuan hitzak azpimarra erabiliz banandu behar direla dio eta Bioconductor gidak, berriz, letra larriz banatzea gomendatzen du.

Izenen formatua ez da gustuaren kontu bat soilik, erabilera ere –hots, tradizioa– aintzat hartzekoa da. Bååth (2012) artikuluan egiten den azterketak tradizio hori zein den islatzen du. Bertan, ikus daiteke aldagaien izenei dagokienez, Googleko gidaren gomendioak direla erabilienak. Funtzioen izenen kasuan aldiz, CRAN biltegitik ateratako datuen arabera, Bioconductor gidan proposatutako formatua da nagusi.

Gida gutxik jasotzen dute klaseei izenak emateko arauak. Horietako bat Bioconductor-enarena da, zeinek izenak letra larriz hastea eta hitzak letra larriak erabiliz banatzea proposatzen duen.

Hau dena kontutan hartuz, hone hemen arau batzuk izenak sortzeko.

R1: Aldagaien izenak. Letra xehez idatzi behar dira eta hitzak puntu ikurraren bitartez banandu behar dira.

nire.aldagaia \[\checkmark\]
nire_aldagaia \[\times\]
Nire.Aldagaia \[\times\]
nireAldagaia \[\times\]
NireAldagaia \[\times\]
nirealdagaia \[\times\]

**R2: Funtzioen izenak.* Lehenengo letra xehea izan behar da eta hitzak letra larrien bitartez banandu behar dira.

nireFuntzioa \[\checkmark\]
nire_funtzioa \[\times\]
nire.funtzioa \[\times\]
Nire.funtzioa \[\times\]
NireFuntzioa \[\times\]
nirefuntzioa \[\times\]

R3: Klaseen izenak. Lehenengo letra larria izan behar da eta hitzak letra larrien bitartez banandu behar dira.

NireKlasea \[\checkmark\]
nire_klasea \[\times\]
nire.klasea \[\times\]
nireKlasea \[\times\]
Nire.Klasea \[\times\]
nireklasea \[\times\]

Fitxategien izenak jartzeko arauak ere gida gutxitan jasotzen dira, eta izena bera baino, hedapena zein izan behar den arautzen da. Edonola ere, fitxategien izenak erabakitzean sistema eragile ezberdinek dituzten berezitasunak ere aintzat hartu behar dira. Esate baterako, Unix sistematan fitxategien izenetan tartea erabiltzea ez da oso gomendagarria, arazoak sor ditzakelako.

Hona hemen fitxategien izenak sortzeko poposaturiko arauak:

R4: Fitxategien izenak. Script fitxategien izenek letra xehez, zenbakiz eta arazorik ematen ez duten karaterez –hala nola, marratxoa edo azpirra– osatuko dira. Hitzak banatzeko, azpimarra erabili eta, beste sinboloentzat –dezimalak banatzeko sinboloa, esate baterako– berriz, marratxoa. A7 Gomendioan arau honen salbuespen bat jasotzen da.

R5: Fitxategien hedapenak. Script fitxategien hedapena .R da, eta ez .r. Datu eta workspacen kasuetan, berriz, fitxategien hedapena .RData izan behar da.

nire_fitxategia.R \[\checkmark\]
nire.fitxategia.R \[\times\]
nireFitxategia.R \[\times\]
NireFitxategia.R \[\times\]
nirefitxategia.R \[\times\]

A.2 Sintaxia

Kodea idaztean, ondoko arau hauek jarraitu behar dira.

R6: Lerroen luzeera. Lerroek 80 karaktereko luzeera izan behar dute, gehienez.

R7: Koskatzea. Kodea koskatzean –begiztetan, esate baterako– bi tarte erabili behar dira, eta inoiz ez tabuladorea.

R8: Esleipenak. Exekutatzen den kodean, beti <-p sintaxia erabili balioak esleitzean. Funtzioak definitzean eta deitzean, berriz, balioak esleitzeko = ikurra erabili.

Beste hainbat lengoaitan gertatzen den legez, R lengoaian kode-blokeak giltza ikurra erabiliz mugatzen dira. Jarraian kode-blokeen inguruko arau batzuko jasotzen dira.

R9: Kode blokeak. Kode-bloke guztiak giltzen artean idatzi behar dira, lerro bakarrekoak ere.

R10: Hasierako giltza I. Ez idatzi hasierako giltza bera bakarrik lerro batean.

R11: Hasierako giltza II. Ez idatzi ezer hasierako giltzaren ostean, iruzkin bat ez bada.

R12: Hasierako giltza III. Ondo koskatu kode-bloke guztiak, kode-blokea erabiltzen duen aginduaren hasiera erreferentziatzat hartuz.

R13: Hasierako giltza IV. Hasierako giltzaren aurretik, tarte bat utzi.

R14: Amaierako giltza. Amaierako giltza bera bakarrik lerro batean idatzi behar da. Arau honek bi salbuespen ditu. Lehenegoa else hitz erreserbatua da, if egituraren lehenengo blokea ixten duen amaierako giltzaren ostean idatziko dena. Bigarren salbuespena funtzio barruan dauden kode-blokeak dira. Kasu honetan, amaierako giltza eta gero funtzioaren deia ixten duen parantesia(k) idatz daite(z)ke.

A.3 Tarteak

Tarte edo hutsuneen erabileraren inguruan konsensu handia egon arren, badaude giden artean zenbait ezberdintasun. Hauen artean = ikurra dago. Googleko gidaren (eta beste zenbait giden) arabera, ikurra horren bi aldeetan tarteak utzi behar dira. Bioconductorreko gidan, berriz, tarterik ez ustea da gomendioa. Guk, kode lerroak albait motzen egitearren, Bioconductorreko gidan proposatutakoari jarrituko diogu.

R15: Eragile bitarrak. Eragile bitar guztiak (hala nola, +, ==, /, etab.) hutsunez inguratu behar dira. Salbuespenak :, :: eta ::: eragileak eta = eragilea funtzio-deietan.

R16: Parentesiak. Funtzio-deietan izan ezik, hasierako parentesiaren aurretik tarte bat utzi.

R17: Komak. Koma baten aurrean, tarterik ez; Koma baten ostean, beti tarte bat utzi.

R18: Lerrokatzeko tarteak. Kodea lerrokatzeko (esleipenak, esate baterako), tarte gehiago sartzea badago. Izan ere, tarte hauen erabilera gomendatzen da, kodearen irakurgarritasuna hobetzen baitute.

R19: Iruzkinak I. Iruzkinetan, beti tarte bat utzi # sinboloa eta gero.

R20: Iruzkinak II. Kodea eta gero idazen diren iruzkinetan, utzi bi tarte # sinboloa baino lehenago.

A.4 Dokumentazioa

R funtzioen dokumentazioa idazteko *.Rd fitxategiak erabiltzen dira, baina sistema hori paketeetan dauden funtzioekin bakarrik erabil daiteke. Guk funtzio bat idazten dugunean, haren dokumentazioa idazteko bi aukera ditugu: roxygen2 paketearen sintaxia erabili (Wickham, Danenberg, and Eugster 2015) edo, Googleko gidan gomendatzen den moduan, funtzioaren kodean bertan dokumentazioa txertatu, iruzkinak erabiliz.

R21: Funtzioen dokumentazioa. roxygen2 paketea erabili ezean, gehitu, funtzioaren hasieran, dokumentazio-iruzkinak. Dokumentazioak, gutxienez, eremu hauek izan behar ditu: Azalpen motz bat (lerro batekoa), argumentuen deskripzioa, funtzioak itzultzen duenaren deskripzioa eta, beharrezkoa balitz, azalpen gehigarriak. Hona hemen egituraren adibide bat.

new.function <- function(arg1, arg2) {
  # Description of what the function does
  #
  # Args:
  #   arg1: Description
  #   arg2: Description
  #
  # Returns:
  #   Description of the result
  #
  # Details:
  #   Any relevant information
  #
  ...
}

A.5 Fitxategien egitura

Estilo-giden xedea kodea ulergarriagoa izatea da. Helburu hori lortzeko, sintaxia ez ezik, script fitxategien antolaketa ere garrantzitsua da. Estiloaren aspektu hau Googleko gidan jasota dago. Jarraian dagoen araua bertan dauden irizpideetan oinarrituta dago.

R22: Fitxategien egitura. Script fitxategiak egitura honen arabaera antolatu behar dira (aukeratu behar diren puntuak kasu bakoitzaren arabera):

  • Copyright eko informazioa.
  • Egile(ar)en informazioa. Fitxategia banatu behar bada, gehitu kontaktu-informazioa.
  • Fitxategiaren deskripzioa.
  • Data eta bertsioari buruzko informazioa.
  • Behar diren source eta library agindu guztiak.
  • Funtzioen definizioa.
  • Konfigurazio-informazioa (bide-izenak, konstanteak, etab.).
  • Exekutatu behar den kodea.

Fitxategien elementuak banatzeko, Wickham-ek iruzkin mota berezia erabiltzea gomendatzen du, kodea zatitzeko.

R23: Kodearen zatiketa. Kodea zatitzeko, - edo = sekuentzia batekin amaitzen duten iruzkinak erabili

A.6 Funtzioak

Atal honek funtzioak idazterakoan aintzat hartu behar diren arau pare bat jasotzen ditu.

R24: Argumentuak. Funtzio-definizioetan, balio lehenetsirik ez duten argumentuak hasieran idatzi behar dira; Balio lehenetsia dutenak argumentuen zerrendaren amaierara gehitu behar dira.

R25: return agindua. Funtzio batek zer edo zer itzultzen badu, return agindua erabili beti.

A.7 Beste arau batzuk

R26: Puntu eta koma. Ez erabili ; ikurra; lerro bat, agindu bat.

R27: Konstante logikoak. Konstante logikoak adierazteko TRUE eta FALSE erabili beti, eta ez T, F, 1 edo 0.

R28: Erabiltzaileari zuzendutako mezuak. Kodearen exekuzioan erabiltzaileari mezuak bidaltzeko message funtzioa erabili. Kodeak konpondu dituen arazoen berri emateko warning funtzioa erabili eta konpondu ez dituen akatsak, error funtzioaren bidez adierazi. cat eta print funtzioak objektuak bistaratzeko soilik erabili.

A.8 Beste gomendio batzuk

Atal honek beste hainbat gomendio jasotzen du. Gomendio hauek ez daude kodearekin zuzenean lotuta eta, hortaz, bere irakurgarritasunean eragin handirik ez dute. Hori dela eta, gomendioak arau maila ez daukate baina, halere, hemen jasotzen direnak kodea idazteko praktika onak dira.

A1: Izenak. Izen motzak eta ezkerretik eskuinera irakurtzen direnak erabili. Ahal den neurrian, funtzioen izenerako aditzak erabili. Saiatu existitzen diren funtzioen izenak ez erabiltzen.

A2: Objektuak. Ez erabili objektuak beharrezkoak ez badira. Egin behar duzuna S3 objektuekin egin ahal bada, ez erabili S4 motako objektuak.

A3: Hizkuntza. Izenak eta iruzkinak idazteko ingelesa erabili beti.

A4: Kopiatu eta itsatsi. Ez kopiatu eta itsatsi kodea. Kode zati bat toki batean baino gehiagotan erabili behar baduzu, funtzio bat sortu.

A5: Paketeak. Askotan erabiliko duzun funtzio-sorta bat baduzu, pakete batean sartzea baloratu.

A6: Fitxategien egitura. Script fitxategi batek lerro asko baditu, kodea fitxategitan zatitu (esate baterako, banatu funtzioen definizioa eta exekutatzen den kodea).

A7: Fitxategien izenak. Fitxategi batean klase bakar baten definizioa badago, jarri fitxategiari klasearen izena. Kasu honetan, R4 araua ez da aplikagarria.

A8: Kode-probak. Kodea probatzen duten funtzioak inplementatu. Helburu hau betetzeko diseinatuta dagoen paketeren bat erabiltzen ez baduzu, jarri proba-funtzioak beste fitxategi batean. Fitxategi hauei izena emateko jatorrizko fitxategien izenari _test.R atzizkia gehitu.

A9: Argumentuak. Funtzio-deietan, erabili beti argumentu=balioa sintaxia, ez bakarrik balioa.

Bibliografia

Genolini, C. 2009. A (Not so) Short Introduction to S4.

Johnson, Paul E. 2015. R Style. an Rcheological Commentary.

Bååth, Rasmus. 2012. “The State of Naming Conventions in R,” R journal, 4 (2): 74–75.

Wickham, Hadley, Peter Danenberg, and Manuel Eugster. 2015. Roxygen2: In-Source Documentation for R. http://CRAN.R-project.org/package=roxygen2.

  1. http://google-styleguide.googlecode.com/svn/trunk/Rguide.xml↩

  2. http://adv-r.had.co.nz/Style.htm↩

  3. http://bioconductor.org/developers/how-to/coding-style/↩

  4. https://csgillespie.wordpress.com/2010/11/23/r-style-guide/↩

  5. https://github.com/tudo-r/PackagesInfo/wiki/R-Style-Guide↩

  6. http://rattle.togaware.com/rattle-rstyle.html↩