Använd en enhetlig stil
Att följa en konsekvent och enhetlig stil gör det möjligt för bidragsgivare i olika miljöer att arbeta tillsammans. Att ena terminologin minskar friktionen i kommunikationen mellan bidragsgivare.
Krav
- Kodbasen MÅSTE använda en stil- eller skrivguide för kod, antingen kodbasgemenskapens egen eller en befintlig som hänvisas till i kodbasen.
- Bidrag BÖR klara automatiserade stiltest.
- Stilguiden BÖR innehålla förväntningar på kommentarer i koden och dokumentation för icke-triviala avsnitt.
- Att ta med förväntningar på begriplig engelska i stilguiden är VALFRITT.
Hur du testar
- Bekräfta att bidrag är i linje med de stilguider som anges i dokumentationen.
- Kontrollera om det finns automatiserade stiltest.
Offentliga beslutsfattare: vad ni behöver göra
- Skapa, följ och förbättra kontinuerligt en stilguide för regelverk och dokumentation och dokumentera det i kodbasen, till exempel i
CONTRIBUTING- ellerREADME-filen.
Chefer: vad ni behöver göra
- Ta med standarder för skriftspråk, källkod, tester och regelverk i er organisations definition av kvalitet.
Utvecklare och formgivare: vad ni behöver göra
Om kodbasen inte redan har tekniska riktlinjer eller annan vägledning för bidragsgivare, börja med att lägga till dokumentation i kodförrådet som beskriver hur det görs nu, till exempel i CONTRIBUTING- eller README-filen.
Ett viktigt syfte med filen är att kommunicera designval, namngivningskonventioner och andra aspekter som maskiner inte enkelt kan kontrollera.
Vägledningen bör innefatta vad som förväntas av källkodsbidrag för att de ska sammanslås av förvaltarna, inbegripet källkod, tester och dokumentation.
Förbättra och utöka dokumentationen fortlöpande med målet att den ska utvecklas till tekniska riktlinjer.
Dessutom:
- Använd en linter.
- Lägg till konfigurationer för lintern i kodbasen.
Vidare läsning
- Programming style på Wikipedia.