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.
Test
- Bekräfta att bidrag följer de stilguider som anges i dokumentationen.
- Kontrollera om det finns automatiserade stiltest.
Offentliga beslutsfattare behöver:
- Skapa, följa och fortlöpande förbättra en stilguide för regelverk och dokumentation och dokumentera det i kodbasen, till exempel i
CONTRIBUTING- ellerREADME-filen.
Chefer behöver:
- Ta med standarder för skriftspråk, källkod, tester och regelverk i er organisations definition av kvalitet.
Utvecklare och formgivare behöver:
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ända en linter.
- Lägga till konfigurationer för lintern i kodbasen.
Vidare läsning
- Programming style på Wikipedia.