Checklista inför publicering av programkod (software)
Vid publicering av programkod är det bra att följa råden nedan, för att göra programkoden så FAIR som möjligt.
Programkod kan publiceras i samma repositorier som används för att publicera forskningsdata. Re3data.org ger en överblick av befintliga repositorier, och ger dig möjlighet att identifiera ett lämpligt repositorium för din specifika kod.
Tänk på följande punkter vid publiceringen:
- Beskriv de programspråk som används i skript (t.ex. C#, Go, Javascript, Python, R) tydligt i metadata och i en README-fil, i förekommande fall även med version.
- Lägg inte README-filen tillsammans med kodskript (eller datafiler) i en zip-fil, utan håll den separat (som .txt eller .md – markdown), för att kunna visas direkt i ett repositorium, så att användare får chansen att bedöma innehållet utan att först ladda ner hela zip-paketet.
- Ge en kort förklarande introduktion till programvaran i inledningen av filen, om möjligt innefattande en versionshistorik och ett exempel på hur programmet kan användas. [1]
- Dela upp programmet/koden i mindre funktioner som fungerar som självständiga återanvändningsbara delar av programvaran. Namnge varje funktion, beskriv vilken information den producerar och lista dess nödvändiga parametrar och argument. [1]
- Undvik duplicering av kod i samma program genom att använda namngivna funktioner istället för att ”klippa och klistra” in samma kodavsnitt på flera ställen. Använd listor istället för att skapa flera variabler av samma slag, t.ex. definiera "score = (1, 2, 3)" hellre än att skapa variablerna "score1", "score2" och "score3". [1]
- Dokumentera och beskriv beroenden och krav på annan mjukvara, med mekanismer för enkel tillgång. [1,2]
- Ge ett enkelt exempel med testdata som kan köras för att se att programmet fungerar och om det ger korrekt output för en känd input. [1]
- Registrera din mjukvara i ett välkänt data- eller kodrepositorium, som också kan ge en beständig identifierare (persistent identifier, PID), vanligen en DOI, till ”frusna” versioner (”releases”) av din mjukvara. Därigenom blir det också lättare för andra att citera din mjukvara och därigenom ge den meritvärde. DOI:s för mjukvara kan fås bl.a. genom Figshare och Zenodo, som båda har en integration med GitHub. Mjukvarukod eller skript för klimatforskning har ett eget lokalt GitLab kodrepositorium genom Bolincentret på Stockholms universitet, som också ger ut DOI:s för ”frysta versioner” (releases) av mjukvarukod eller skript. Mer information och hjälp kan fås genom Bolincentrets supportsida.
- Vi rekommenderar att all mjukvara som produceras i forskningsprojekt vid Stockholms universitet så långt som möjligt får en användarlicens för öppen källkod. Lista med exempel på öppen källkod https://spdx.org/licenses/. [3]
- För att slippa skriva mer än nödvändigt och få maximal nytta av “autoutfyllnad” (med tab-tangenten) av variabel-, mapp- och filnamn, gör dessa till unika strängar så långt möjligt med skilda begynnelse (och så att inget mapp- eller filnamn bara är en ”delsträng” av ett sådant namn i samma filstruktur). Använd bara den (av Riksarkivet) begränsade teckenuppsättningen [A-Za-z0-9-_.] till filnamn och mappar, utan några mellanslag.
[1] Wilson et al. (2017): Good enough practices in scientific computing.
[2] Lamprecht et al. (2020): Towards FAIR principles for research software.
[3] Akhmerov et al. (2019): Raising the Profile of Research Software.