Koodi väärin, Corpus väärin vai molemmat – Corpus 2/3
AI
Kun vertasimme liiketoiminnan kuvausta ja koodia automaattisesti toisiinsa, löysimme ongelmia, joita yksikään testi ei olisi löytänyt.
Teksti: Arttu Ylärakkola
Corpus on projektin versionhallinnassa oleva hakemisto markdown-tiedostoja. Ne kuvaavat järjestelmän liiketoiminnan tasolla: sanaston, roolit, prosessit ja päätökset. Edellisessä kirjoituksessani kerroin, miksi nopea koodi synnyttää kognitiivista velkaa.
Kun samassa repossa on sekä koodi että selkokielinen kuvaus siitä, mitä koodin pitäisi tehdä, tekoäly voi verrata niitä toisiinsa. Ja kun se vertaa, se löytää ristiriitoja.
Kolme lajia ristiriitoja
Koodin ja Copruksen pitäisi kertoa järjestelmästä samaa tarinaa. Jos tekoäly löytää niiden väliltä eron, jompikumpi on väärässä. Tai molemmat. Jokainen löytämämme poikkeama kuului johonkin kolmesta lajista.
Ensimmäinen laji on arkista ylläpitoa. Joku muutti toimintaa, mutta Corpus jäi päivittämättä. Korjaus on nopea, mutta tärkeä: jos Corpus jää vääräksi, tekoäly tekee seuraavan tehtävän väärän oletuksen varassa.
Toisessa lajissa sääntö on kirjattu ja liiketoiminta luottaa siihen, mutta jossain refaktoroinnissa koodi lakkasi noudattamasta sääntöä. Testit menevät läpi, koska kukaan ei kirjoittanut testiä juuri sille asialle. Koodia lukemalla tätä bugia ei löydy, koska koodi näyttää olevan ok. Vika näkyy vasta, kun tietää, mitä koodin pitäisi tehdä.
Kolmannessa lajissa sekä koodi että Corpus ovat väärin, mutta kyse on harvoin huolimattomuudesta. Yleensä muutos on tehty tilanteessa, jossa kukaan ei ollut sopinut, mitä muutoksen pitäisi tarkoittaa. Kehittäjä tulkitsi tiketin yhdellä tavalla, Corpukseen kirjattiin toinen tulkinta ja liiketoiminnalla oli mielessään kolmas. Kehittäjä tulkitsi tiketin yhdellä tavalla, Corpukseen kirjattiin toinen tulkinta ja liiketoiminnalla oli mielessään kolmas.
Tätä ei ratkaista koodaamalla, koska kyse on tekemättömästä liiketoimintapäätöksestä. Ristiriita on ensimmäinen hetki, jolloin puute tulee näkyviin. Ilman vertailua se olisi tullut näkyviin vasta, kun asiakas soittaa ja valittaa.
Entä kun tekoäly on väärässä?
Kaikki automaattisesti löydetyt poikkeamat eivät aina osu oikeaan. Tekoäly tulkitsee joskus asioita väärin, ja osa hälytyksistä on turhia.
Silti hälytykset paljastavat erittäin usein jotain, mikä koodissa pitää oikeasti korjata. Hälytys vie katsomaan kohtaa, jossa onkin pielessä jotain muuta. Siksi Corpusta ei pidetä kunnossa sen itsensä vuoksi. Tavoitteena ei ole kiiltävä dokumentaatio vaan se, mitä ristiriidat kertovat järjestelmästä.
Corpuksen korjaaminen vie vähän aikaa, mutta jokainen korjaus poistaa väärän oletuksen, jonka varassa tekoäly oli toiminut. Sen voi korjata kerran tai maksaa siitä jokaisessa tehtävässä erikseen.
Ristiriitoja voi myös ehkäistä etukäteen. Kun toimintaa muuttava pull request sisältää Corpus-päivityksen, katselmoinnissa on kaksi diffiä: koodi ja kuvaus. Kuvauksen diffistä teknisesti oikean mutta liiketoiminnan kannalta väärän muutoksen huomaa helposti, ja sen voi lukea kuka tahansa, joka tuntee liiketoiminnan.
Kokeile itse!
Teimme esimerkkirepon osoitteeseen github.com/rakettitiede/corpus. Sen koodikantaan on jätetty tarkoituksella ristiriitoja koodin ja Corpuksen välille. Mukana on esimerkki tekoälyskillistä /corpus-check, joka raportoi, mikä on pielessä: koodi, Corpus vai molemmat.
Repossa on myös skripti, joka tekee siitä kopion ilman Corpusta ja muita asioita, joista tekoäly voisi lunttia. Voit siis kysyä samat kysymykset kahdesti ja verrata, miten tekoäly vastaa Corpuksen kanssa ja ilman.
Esimerkki on tietysti vain esimerkki. Oikeat järjestelmät ovat paljon monimutkaisempia, ja juuri niissä Corpuksesta on eniten hyötyä.
Mihin tämä on menossa?
Tällä hetkellä tarkistukset ajetaan kehittäjän koneella commitin tai pushin yhteydessä. Luonteva seuraava askel olisi Dependabotin kaltainen botti, joka tarkkailee repoa ja tekee pull requestin, kun koodi ja Corpus ajautuvat erilleen.
Yksi asia on selvä jo etukäteen: jos botista tulee liian äänekäs, kukaan ei lue sen pull requesteja. Täydellistä kattavuutta tärkeämpää on se, että harvat osumat ovat oikeasti tärkeitä.
Sarjan viimeisessä osassa kerron, mitä Corpukseen kannattaa laittaa ja mitä ei.
Lue Corpus-sarjan kaikki osat:
1/3: Teknisesti täydellinen, käytännössä väärä: miksi nopea koodi synnyttää kognitiivista velkaa
2/3: Koodi väärin, Corpus väärin vai molemmat? Kolme ristiriitaa, jotka paljastavat enemmän kuin testit (eiku senhän sä just luit!)
3/3: Corpus omaan repoon: mitä hakemistoon kannattaa laittaa ja mitä ei
Mikä on Corpus?
Corpus on projektin versionhallinnassa oleva hakemisto markdown-tiedostoja. Ne kuvaavat järjestelmän liiketoiminnan tasolla: sanaston, käyttäjäroolit ja niiden motiivit, prosessien kulun sekä tehdyt päätökset. Tiedostoja voi lukea kehittäjä, liiketoiminnan ihminen tai tekoäly, ja ne päivitetään aina, kun järjestelmän toiminta muuttuu.
Koodi kertoo tekoälylle, miten järjestelmä toimii. Corpus kertoo, miksi.
Corpus ei ole tuote eikä siihen ole lisenssiä. Se on pelkkä versioitu hakemisto tekstitiedostoja, joten se toimii minkä tahansa kielen, työkalun ja menetelmän kanssa. Emme väitä keksineemme sitä. Ajauduimme tähän työtapaan omissa projekteissamme ja annoimme sille nimen Corpus.
Esimerkkirepo: github.com/rakettitiede/corpus