Avainsana: vinkit

Versionhallinnasta ja siihen liittyvistä asioita on kirjoitettu paljon, mutta useissa kirjoituksissa on keskitytty lähinnä teknisiin asioihin ja eri versionhallintajärjestelmien mahdollistamiin asioihin. Harvat kirjoitukset keskittyvät käytännön asioihin ja niin sanottuihin parhaisiin käytäntöihin, joita soveltamalla versionhallinnan käytöstä saa paljon enemmän irti.

Muutamia käteväksi todettuja ja omasta mielestäni ”parhaita käytäntöjä” koodaajan näkökulmasta ovat muun muassa:

1. Työn kulku
2. Vie koodi versionhallintaan usein ja aikaisin
3. Vie yhtenäisiä kokonaisuuksia
4. Kirjoita järkeviä commit-viestejä
5. Tee koodaustyylin muutokset erillään oikeista muutoksista
6. Älä vie tiedostoja, jotka muuttuvat dynaamisesti
7. Älä vie koodia, joka ei käänny

1. Työn kulku
”Version Control with Subversion” -kirja selvittää normaalin työn kulun, joka on hyvä omaksua versionhallintaa käytettäessä (hieman sovellettuna):

1. Hae koodista tuorein versio versionhallinnasta
2. Toteuta koodiin tehtävät muutokset
3. Hae tuorein versio ennen koodin vientiä versionhallintaan
4. Aja testit uudestaan ja varmista, että tekemäsi muutokset toimivat
5. Vie koodi versionhallintaan yhtenä kokonaisuutena
6. Selvitä konfliktit
7. Tarkista, että versio kääntyy myös build-palvelimella
8. Korjaa virheet tai palauta

2. Vie koodi versionhallintaan usein ja aikaisin
On suositeltavaa toteuttaa Check In Early, Check In Often -periaatetta. Tällöin muut näkevät mitä olet tekemässä ja koodi on muidenkin käytössä.

”If the code isn’t checked into source control,
it doesn’t exist.” – Coding Horror

Lisäksi jos piilottelet koodia omalla koneellasi, etkä synkronoi sitä versionhallintaan pitkään aikaan, voi muutosten yhdistämisestä tulla erittäin työlästä. Pieniä kokonaisuuksia on helpompi verrata ja saadaan aikaan vähemmän konflikteja.

Vaikka idean järkevyys ja käytännöllisyys on helppo ymmärtää, on käytännön toteutus usein jotain muuta. Itse olen ainakin huomannut, että omaa koodia tulee helposti pantattua levyn nurkalla, kunnes kyseinen ominaisuus on ”valmis” ja testattu.

”Hiding your code until it’s ”done” may feel safer, but it isn’t. Sharing your ongoing code with your coworkers is scary, much less the world — but it also results in feedback and communication that will improve your code and draw you closer to the project you’re working on.” – Coding Horror

3. Vie yhtenäisiä kokonaisuuksia
On suositeltavaa viedä versionhallintaan loogisesti yhtenäisiä kokonaisuuksia. Tämä tekee versiohistorian seuraamisesta huomattavasti hyödyllisempää, etenkin jos muutokset käsittelevät useita eri tiedostoja.

Eli, jos teet useita yhtäaikaisia muutoksia, jaa ne useampaan loogiseen kokonaisuuteen ja vie ne osissa. Näin yksittäisten muutosten historiaa on helpompi seurata ja nopeuttaa mahdollisten bugien metsästystä myöhemmin. Jos siis teet ominaisuutta A, B ja C sekä korjaat bugeja 1, 2 ja 3, pitäisi niistä muodostua vähintään kuusi committia. Vastaavasti, jos teet suuria muutoksia tai toteutat itsenäisiä muutoksia useisiin loogisiin moduleihin, vie muutokset erikseen, vaikka ne olisivatkin osa isompaa kokonaisuutta.

Käytännössä sitä kuitenkin usein huomaa koodaavansa hieman sieltä sun täältä sitä ja tätä, ja lopulta järkevän yhtenäisen kokonaisuuden vieminen versionhallintaan on käytännössä mahdotonta.

Tietenkin tätä periaatetta on helpompi noudattaa sovelluksen ylläpidossa kuin sovelluksen kehittämisessä, jossa puutteellisia ja koodausta kaipaavia asioita on paljon. Teoriassa järkevä ”commit”-tapa on helppo omaksua, mutta käytännössä yhtenäisen kokonaisuuden siirtäminen versiohallintaan vaatii itsekuria ja koodauksen suunnittelua.

4. Kirjoita järkeviä commit-viestejä
Kirjoita aina jokin kommentti viedessäsi koodia versionhallintaan. Kommentin tulisi olla lyhyt ja ytimekäs, ja kertoa mitä muutettiin ja miksi. Jos teit useita muutoksia, kirjoita ne omille riveilleen.

On myös kätevää lisätä kommentin eteen jokin tunniste kuten Fix tai Add, viitaten minkä tyyppisiä muutoksia teit. Tämä myös helpottaa sisällön filtteröintiä myöhemmin.

Korjatessa jotain tiettyä bugia tai pyydettyä ominaisuutta, on suositeltavaa lisätä bugin tai issuen numero commit-viestiin.

”If the changes you made are not important enough to comment on, they probably are not worth committing either.” – loop label

5. Tee koodaustyylin muutokset erillään oikeista muutoksista
Koodaustyyli voi kokea muutoksia ja kehitysvälineessä voidaan esimerkiksi ottaa käyttöön automaattiset koodimuotoilut. On erittäin suositeltavaa, että koodin muotoiluun vaikuttavat muutokset tehtäisiin erillään oikeista muutoksista.

Jos koodimuotoilut ja muutokset sekoitetaan keskenään, on muutosten jäljittäminen ja kohdistaminen käytännössä mahdotonta.

6. Älä vie tiedostoja, jotka muuttuvat dynaamisesti
Versionhallinnassa olevien tiedostojen olisi hyvä olla sellaisia, joiden sisällöstä valta on käyttäjillä eikä esimerkiksi kehitysympäristöllä. Esimerkiksi ei kannata viedä Eclipsen asetuksia tai projekti-tiedostoa, jotka muuttuvat riippuen kehittäjän haluamista asetuksista. Kyseiset tiedostot eivät varsinaisesti liity projektin koodiin ja aiheuttavat vaan turhaa synkkaamista. Myös projektin binäärit ja Javadocit voidaan mieltää turhiksi versionhallinnan näkökulmasta.

(via Perforce)

7. Älä vie koodia, joka ei käänny
Ei ole suositeltavaa viedä versionhallintaan koodia, joka ei käänny ja hajottaa projektin myös muille kehittäjille. Toisaalta, ideaalissa tilanteessa, ei pitäisi koskaan lähteä toimistolta viemättä koodia versionhallintaan.

Jos teet muutoksia, jotka vaikuttavat muihin, harkitse koodin branchaamista muutoksen toteuttamiseksi ja yhdistä koodi, kun olet valmis. Toisaalta, toimimaton koodi ei ole syy olla viemättä sitä versionhallintaan.

”It’s better to have a broken build in your working repository than a working build on your broken hard drive.” – loop label

Yhteenveto
Versionhallinnan käyttö on omaksuttu osaksi sovelluskehitystä ja toivottavasti edes osa yllä olevista periaatteista on jo useimpien kehittäjien käytössä. Ellei käytössä olevia työvälineitä hyödynnetä kunnolla, jää paljon etuja saavuttamatta. Edes muutaman yllä olevan käytännön omaksuminen kuten ”loogiset kokonaisuudet” ja ”commit-viestit”, helpottaa jo kummasti.

Versionhallinta on käsitteenä laaja ja sen käyttöön liittyy paljon muitakin asioita, joista voidaan määritellä niin sanotut parhaat käytännöt. Tälläisiä ovat muun muassa koodin hallintaan liittyvät asiat, versionhallinnan soveltaminen ja toimintojen laajentaminen, mutta ei niistä sen enempää.