Muistio Sovellusprojekti Verso, 1. koodin katselmointi Paikka: AgC226.2, Agora Aika: maanantai 29.3.2010 klo 10:15-11:20 Muistio laadittu: 1.4.2010 Muistiota muokattu: 14.4.2010 Läsnä Projektiryhmä (3/4) Tero Hänninen Marko Peltola Heikki Salo Ohjaajat Antti-Juhani Kaijanaho Jukka-Pekka Santanen 1. Katselmointitilanne Kaijanaho oli käynyt läpi projektiryhmän katselmoitavaksi esittämiä lähdekooditiedostoja. Kaijanahon esittäessä huomioitaan projektiryhmä esitteli lähdekoodia videoprojektin avulla. 2. Metatiedostot: app/helpers/grmf_helper.rb Kaijanaho kysyi projektiryhmältä, mitä he itse ajattelivat koodista. Tero kertoi, että metatiedostoja käsittelevä koodi on mukavasti erotettu muusta toiminnallisuudesta. 2.1 Muuttujien nimeämistä Kaijanaho nosti esille koodissa esiintyvän muuttujannimen "obj" ja totesi, että vaikka muuttujat on koodia kirjoittaessa luontevaa nimetä nopeasti, ei "obj" kerro muuttujan käyttötarkoituksesta mitään. Myös repository-modelia edustava "repo" ja Grit-repository -objektia edustava "rep" ovat hämmentävästi nimetty. grmf_helper.rb:ssä oli myös pari turhaa paikallista muuttujaa, jotka poistamalla koodi lyhenisi. 2.2 Kommenteista Kaijanaho oli generoinut lähdekoodista rdoc-tiedostot. Kaijanaho huomatti, että vaikka grmf_helper.rb:n lähdekooditiedostossa oli moduulin kommenteissa hyvä kuvaus, se oli rajattu lisenssin mukana -- ja ++ -operaattoreilla generoitavasta moduulikommentista pois. 2.3 includen/requiren käytöstä Projektiryhmä oli käyttänyt grmf_helper.rb:n yhteydessä include-käskyä. Kaijanaho huomautti sillä toteutettavan Rubyssä eräänlaista moninperintää, mikä ei tässä yhteydessä ole haluttua. Tässä tarvittava käsky olisi require. 2.4 Helperin roolista grmf_helper.rb oli kirjoitettu Helper-moduuliksi. Kaijanaho oli kuitenkin huomannut Helpereitä käytettävän pääasiassa näkymien yhteydessä ja ehdotti grmf_helper.rb:n toimintojen siirtämistä joko omaksi kirjastokseen lib-hakemiston alle tai repository-modeliin. Kaijanaho näki, että vaikka grmf_helper.rb:n sijainti ei nykyisellään ole välttämättä väärin, tämä olisi hyvä siistiä jos koodia tarjotaan Gitorious-mainlineen. 3 Repository browser 3.1 app/controllers/site-controller.rb Kaijanaho kysyi ryhmän kommentteja Repository browser -ominaisuuden toteutusratkaisuista. Ryhmä kertoi, että se on tällä hetkellä väärässä controllerissa (site_controller), koska tarvittavaa reititystä omaan controlleriin ei saatu tehtyä. Kaijanaho kysyi, miksi ohjelmaosioiden toteuttajien nimiä ei ole listattu lähdekooditiedostoon muiden tekijöiden joukkoon. Salo kertoi, että nimien lisäämiseen liittyvistä käytänteistä on ollut tarkoitus kysyä erikseen. Kaijanaho sanoi, että muokkaajien nimet olisi joka tapauksessa hyvä lisätä aina tiedostoa muokatessa. Kaijanaho oli lähettänyt Repository browser -kokonaisuudesta perjantaina bugiraportin, johon ryhmä ei ollut vielä ehtinyt tutustua. 3.2 ../site_controller.rb, create_repo_and_project-metodi Kaijanaho arveli, että hänen edellä viittaamansa ongelma johtuu todennäköisesti siitä, että create_repo_and_project-metodissa kutsutaan mahdollisesti kahdesti render-komentoa. Render-komentoa saisi sivua muodostettaessa kutsua vain kerran. Santanen kysyi, voisiko metodissa olevaa pitkää riviä jakaa kahtia. Santanen huomautti lisäksi, että projektiryhmän tekemät lähdekoodit pitää tulostaa jossain vaiheessa. Kaijanahonkin mielestä oli parempi, jos jokainen lähdekoodirivi mahtuisi 80 merkkiin. Kaijanaho kiinnitti huomiota koodissa näkyvään merkintään, jossa ilmoitetaan isoilla kirjaimilla kommentti. Projektiryhmä oli jättänyt sen merkiksi, jotta oma koodi löytyy sen väliaikaisesta sijoituspaikasta nopeammin. Santanen huomautti, että harkitun kommentin olisi hyvä päättyä pisteeseen. 3.3 app/views/repositories/_list.html.erb Tämänkin tiedoston kohdalla keskusteltiin siitä, miksi tiedostosta puuttuu ohjelmaosion toteuttajien nimet sekä siitä, kuuluuko ryhmän toista tiedoa pohjana käyttäen muodostetussa tiedostssa olla Nokian copyright-merkintä. _list.html.erb:ssä oli rikkinäinen h3-tagi. Ilmeisesti tagista uupuu class-attribuutin määrittely. Myös muutamaan html-tagiin oli merkattu style-attribuuttiin tyylimääritely, jotka olisi parempi siirtää CSS-classiin. 4 Loppuhuomiot Kaijanaho kertoi, että läpikäyty tilaisuus ei vastaa sitä, mitä työelämässä tarkoitetaan koodin katselmoinnilla. Vaikka nykyiselläänkin tilaisuudesta on varmasti hyötyä, tässä tilaisuudessa koodia kommentoi koodille täysin vieras asiantuntijataho. Työelämässä katselmointitilaisuus koostuu kanssaohjelmoijien vertaispalautteesta ja on aikaavievä tilaisuus. Lopuksi oli vielä puhetta Ruby-koodista generoitavista rdoceista. Santanen sanoi, että rdoccien tuottaminen olisi varmaankin paras tapa tulostaa koodista luokkadokumentaatio projektikansioon. tarkistaa kommenttien olemassaolo ja järkevyys. Santanen sanoi luokkadokumentaation tuottamisen olevan kätevä tapa