The Value of Effective Pull Request Description
Deze empirische studie toont aan dat, hoewel ontwikkelaars pull request-beschrijvingen belangrijk vinden, het specifiek vermelden van de gewenste feedback het sterkst voorspelt of een wijziging wordt geaccepteerd en reviewers betrokken raken.
Oorspronkelijk artikel gelicentieerd onder CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/). Dit is een AI-gegenereerde uitleg van het onderstaande artikel. Het is niet geschreven of goedgekeurd door de auteurs. Raadpleeg het oorspronkelijke artikel voor technische nauwkeurigheid. Lees de volledige disclaimer
Stel je voor dat software ontwikkelen een gigantische bouwplaats is. Iedereen werkt samen aan één groot gebouw (de code). Soms wil een werknemer een nieuwe deur toevoegen of een muur verplaatsen. Maar voordat die verandering echt wordt aangebracht, moet hij of zij een aanvraag indienen. In de wereld van software noemen we dit een "Pull Request" (PR).
Deze aanvraag is als een briefje dat je op de deur van de bouwplaats plakt. Het zegt: "Kijk eens, ik heb dit gedaan. Mag ik dit nu vastzetten?"
Deze studie van onderzoekers van de Universiteit van Zürich en INESC TEC kijkt naar één heel specifiek onderdeel van die briefjes: de beschrijving. Soms schrijven mensen een heel verhaal erbij, soms staat er alleen een puntje, en soms is het briefje helemaal leeg.
Hier is wat ze hebben ontdekt, vertaald naar alledaags taal:
1. De "Recept" voor een goede aanvraag
De onderzoekers keken eerst naar alle handleidingen en blogs van experts. Ze maakten een lijstje van de 8 beste onderdelen die in zo'n beschrijving zouden moeten staan. Denk hierbij aan:
- Het doel: Waarom doe je dit? (Bijvoorbeeld: "Ik maak de deur rood omdat de klant dat wil.")
- De uitleg: Hoe heb je het gedaan? (Bijvoorbeeld: "Ik heb de verflaag verwijderd en een nieuwe aangebracht.")
- De tests: Heb je gecontroleerd of het niet lekkt?
- De vraag aan de inspecteur: Wat wil je dat de inspecteur precies kijkt?
2. Wat zeggen de cijfers? (De "Grote Foto")
De onderzoekers keken naar 80.000 van deze aanvragen op GitHub (een grote website voor programmeurs). Ze keken of een goede beschrijving leidde tot snellere goedkeuringen, minder discussie of meer kans dat de verandering werd aangenomen.
Het resultaat was verrassend:
- De "Waarom"-verhalen zijn belangrijk: Als iemand uitlegt waarom ze iets doen (het doel) en hoe ze het hebben getest, is de kans groter dat de verandering wordt goedgekeurd. Het is alsof je aan de bouwmeester uitlegt dat de rode deur nodig is voor de veiligheid; dan luistert hij sneller.
- De "Vraag"-truc werkt het beste: Het meest krachtige onderdeel bleek niet de technische uitleg te zijn, maar het specifiek vragen om feedback. Als een programmeur schrijft: "Kijk vooral even of de scharnieren goed zitten," dan gebeurt er iets magisch: de inspecteur wordt actiever, het gesprek wordt rijker, en de kans dat de aanvraag wordt goedgekeurd stijgt met 64% tot 72%.
- Analogie: Het is alsof je een gast uitnodigt voor een diner en zegt: "Probeer vooral de saus." De gast let dan extra op die saus, en het diner wordt een succes. Als je niets zegt, kijkt de gast misschien alleen naar de borden.
3. Wat vinden programmeurs zelf?
De onderzoekers spraken ook met 64 programmeurs.
- Iedereen vindt het belangrijk: Programmeurs zeggen unaniem dat een beschrijving cruciaal is. Zonder beschrijving is het alsof je een raadsel moet oplossen zonder hints. Je snapt niet waarom iets is veranderd, en dat maakt het moeilijk om te controleren of het goed is.
- Maar ze doen het niet altijd: In de praktijk zien ze dat mensen vaak geen beschrijving schrijven. Waarom? Omdat ze het te druk hebben, of omdat ze denken dat de code "voor zichzelf spreekt".
4. Wanneer schrijven mensen wel een beschrijving?
De studie toonde aan dat mensen geen automatische piloot gebruiken. Ze passen zich aan aan de situatie:
- Complexe klussen: Als de verandering heel ingewikkeld is (een heel nieuw trappenhuis in plaats van een deur), schrijven mensen wel een beschrijving. Ze weten dat ze anders niet begrepen worden.
- Oude projecten: In projecten die al lang bestaan, is de cultuur om te schrijven sterker.
- De "Te druk"-factor: Als iemand heel veel werk heeft of als de verandering heel simpel is (een lettertje aanpassen), laten ze de beschrijving vaak weg.
Conclusie: De "Slimme Brief"
De belangrijkste les uit dit onderzoek is dat een Pull Request-beschrijving twee dingen moet doen:
- Uitleggen: Wat is er veranderd en waarom? (Dit helpt de geschiedenis van het gebouw vast te leggen).
- Sturen: Zeg de inspecteur precies waar hij moet kijken.
Het is niet nodig om een dik boek te schrijven bij elke kleine verandering. Maar als je echt wilt dat je idee wordt goedgekeurd en dat de inspecteur meedenkt, is het slim om te zeggen: "Hier is wat ik heb gedaan, en ik wil dat jij vooral kijkt naar..."
Kortom: Een goede beschrijving is niet alleen een verslag van wat er gebeurd is, maar een uitnodiging voor de inspecteur om samen met jou aan het werk te gaan.
Verdrinkt u in papers in uw vakgebied?
Ontvang dagelijkse digests van de nieuwste papers die bij uw onderzoekswoorden passen — met technische samenvattingen, in uw taal.