Guidelines for a healthy code review culture/cs

Přezkoumání kódu je emocionální práce: Jsme emocionální bytosti, které jsou do této práce emocionálně investovány, až po kód, který píšeme. Poskytování a přijímání zpětné vazby je těžké a my všichni musíme tuto zátěž sdílet, abychom vybudovali zdravou kulturu kontroly kódu.

Přední je kontrola kódu pro zabránění rozbití věcí a udržování stavu kódu. Ve skutečnosti je to (a mělo by být) mnohem víc než to.



Cíle kontroly kódu

 * 1) Společně zabránit tomu, aby se defekty nebo zranitelnosti dostaly do produkčního kódu
 * 2) Podporovat udržovatelnost, předcházet budoucí frustraci a zmatku
 * 3) Poskytnout příležitost ke vzdělávání, aby se spolupracovníci mohli učit a růst, a přivádět nové spolupracovníky
 * 4) Podporovat sdílené porozumění, vlastnictví a odpovědnost za kód prostřednictvím spolupráce, což vede k funkčnějšímu a plnějšímu týmu přispěvatelů

V konečném důsledku je kontrola kódu dialog, který je pro naše hnutí obzvláště důležitý, protože většina naší práce se provádí vzdáleně a asynchronně. Všichni jsme součástí komunity kontrolorů kódu a spolupráce na budování důvěry v této komunitě nám pomůže dosáhnout cílů kontroly kódu, podpořit stávající členy komunity a přivést nové členy.



Co dělá kulturu kontroly kódu zdravou?
"Zdravá kultura kontroly kódu je kultura, ve které je zpětná vazba vítána bez obav."

Pojďme si to rozebrat:


 * Zpětná vazba je vítána: Ve zdravé kultuře kontroly kódu získávání zpětné vazby znamená, že byla zachycena závada před uvedením do provozu. Práce v tomto druhu kultury je naplňující.
 * Beze strachu: Psychologická bezpečnost je základem zdravé kultury kontroly kódu. Lidé se musí cítit pohodlně při poskytování a přijímání zpětné vazby. Odeslání opravy nebo poskytnutí kritiky může být zastrašující a tento proces vyžaduje důvěru. Lidé, kteří se cítí bezpečně, jsou více schopni navrhovat nové nápady, experimentovat a růst. Lidé, kteří se necítí bezpečně, nakonec přestanou přispívat a odejdou.

Tento druh kultury můžeme vytvořit tím, že definujeme naše hodnoty a aplikujeme je na to, jak pracujeme.



Hodnoty zdravé kultury kontroly kódu


Respekt a empatie nad egem

 * Náš kód nás nedefinuje: Přestože jsme hodně investovali do kódu, který píšeme, kódování je to, co děláme, ne to, kým jsme. Kritizujte kód, ne kodéra.
 * Veďte se soucitem: Začněte u sebe a pak to rozšiřte na všechny. Všichni teď děláme to nejlepší, co můžeme.
 * Budujte důvěru: Laskavost, empatie a zvědavost mohou budovat vztahy mezi spolupracovníky. Důvěra vede k psychickému bezpečí, což vede ke skvělé práci a šťastným přispěvatelům.
 * Předpokládejte kompetence: Ptejte se spíše než předpokládejte neschopnost. Možná jste to vy, kdo něčemu nerozumí.
 * Uvědomujte si dynamiku síly: Naslouchejte lidem, kteří mají méně zkušeností než vy. Zvedněte tiché hlasy. Často se oddávejte ostatním.



Spolupráce nad konkurencí

 * Zaměřte se na spolupráci: Když se soustředíte na spolupráci, ego vám nebude překážet. Spolupráce umožňuje více lidem přispívat a vede k lepšímu produktu.
 * Uvědomte si výzvy spolupráce: Pro některé z nás je obtížné řídit svůj tón, někteří z nás se potýkají s tím, že se musíme vzdát řešení, která se nám nelíbí, a někteří z nás zadržují kritickou, ale užitečnou zpětnou vazbu. strach z toho, že bude vypadat negativně. Pamatujte, že každý je jiný, ale všichni můžeme růst.
 * Přijměte zpětnou vazbu jako dárek: Ve zdravé kultuře bude každá zpětná vazba vítána jako něco, co zlepšilo kód, něco nás naučilo nebo nás přimělo přemýšlet.
 * Podporujte zvědavost a experimentování: V bezpečném prostředí se můžeme učit, inovovat a bavit se hrou.
 * Nesouhlas s pokorou: Když nesouhlasíš, řekni svůj názor uctivě a buď otevřený tomu, aby se tvůj názor změnil. Zeptejte se sami sebe, jestli na něčem opravdu, opravdu záleží. Buďte ochotni dát šanci alternativním řešením.



Záleží na tom, jak komunikujete

 * Zvažte svůj tón: Tón ovlivňuje morálku. Určuje, zda je kontrola kódu produktivní, povzbuzující a naplňující proces, nebo zastrašující, frustrující a zraňující. Laskavý, uctivý a neodsuzující tón učiní lidi otevřenějšími konstruktivní zpětné vazbě. $1 Komentáře "X je špatně" a "Uvažovali jste o Y?" mají velmi odlišné účinky.   The comments “X is wrong” and “have you considered Y?” have very different effects.
 * Neuvádějte názor jako fakt: Mohli byste ukončit diskusi. Místo toho…
 * Ptejte se a dávejte doporučení: Poskytněte kontext, vysvětlete, jak by mohl být kód lepší, a nastiňte dopad jeho změny. Poskytněte odkazy na dokumentaci – tím prokážete, že jste ji museli alespoň jednou vyhledat.
 * Zeptejte se "Co si o tom myslíte?" a poslouchejte odpověď.
 * Pokud něco uvádíte jako fakt, ujistěte se, že máte pravdu: Jinak bude autor kódu ztrácet čas a bude frustrovaný. Pokud je to možné, uveďte reference. Pokud si něčím nejste jisti, zeptejte se místo toho.
 * Ujasněte si, co je funkční závada a co preferujete: Můžete zvážit výslovně označit vaše komentáře jako takové.
 * Vyjádřete vděčnost a povzbuzení: "Pozitivnost“" je nabitý termín a rady jako "každé recenzi přidejte pochvalu" se mohou zdát falešné nebo zbytečné. Místo toho si uvědomujte příležitosti k pochvale: Pokud jste se něco naučili nebo na vás udělalo dojem, řekněte to. Vděčnost a povzbuzení mohou být součástí každé recenze: I prosté "Díky, že to děláte" nebo "Dobrá práce!" s vaším +2 je rozdíl, protože pozitivní zpětná vazba motivuje k dalším příspěvkům a činí lidi otevřenějšími kritické zpětné vazbě.
 * Vynechejte soudy a sarkasmus: Kontrolujte samotný kód, ne autora. Pamatujte, že každý dělá chyby a má prostor k růstu a dobří spolupracovníci si navzájem pomáhají růst. Posuzující nebo sarkastické komentáře nemají místo v kolaborativním, produktivním hodnocení kódu.
 * Uvědomujte si lidi, které možná umlčujete: Kultura negativity a neústupné kritiky umlčuje důležité hlasy.



Pamatujte na větší obrázek

 * Neztrácejte ze zřetele kontext: Místo toho, abyste se soustředili na obskurní problémy nebo hlouposti, zaměřte se na celkové místo kódu v kódové základně. Zvažte širší cíl a položte si otázku: "Je tato zpětná vazba cenná?" Kontrola po řádcích je důležitá, ale měla by být provedena v kontextu projektu jako celku. Projektu můžete z dlouhodobého hlediska více pomoci tím, že budete přispěvatele spíše povzbuzovat než frustrovat.
 * Pochopte a přizpůsobte se různým kontextům recenzí: U významného, komplexního patche, jehož autorem je zkušený přispěvatel, může být primárním cílem vylepšit a posílit technické řešení. Pro malý patch nahraný novým přispěvatelem je důležitější inkluze a vzdělání. Přizpůsobte svůj jazyk a úroveň kritiky aktuálnímu kontextu.
 * Nezanechejte lavinu komentářů:$1 Zanechání velkého množství komentářů najednou může být pro autora zdrcující, zvláště pokud to dělá více recenzentů. Je snadné se cítit jako spřízněný. Pokud se přistihnete, že zanecháváte dvouciferný počet komentářů, zejména na menším patchi, zeptejte se sami sebe, zda jsou tyto komentáře opravdu nutné nebo přidávají hodnotu. Pokud musíte zanechat mnoho komentářů, vezměte to na vědomí, v ideálním případě soukromě oslovte autora. Nabídněte pomoc a buďte extra laskaví. Leaving a lot of comments at once can be overwhelming for the author, especially if done by multiple reviewers. It’s easy to feel ganged-up on. If you find yourself leaving a double-digit number of comments, especially on a smaller patch, ask yourself if these comments are really necessary or adding value. If you do have to leave a lot of comments, acknowledge this, ideally by reaching out to the author privately. Offer help and be extra kind.
 * Nechte to: S grácií přijměte kompromis nebo porážku. $1 Pokud to není součástí dokumentovaných standardů, upřednostněte preference autora kódu. Pamatujte, že neexistuje nic takového jako dokonalý kód: Pátrání po nedosažitelné dokonalosti vede k frustrovaným přispěvatelům a pomalému pokroku. Zeptejte se sami sebe: "Jaký je nejhorší scénář, pokud se tento kód sloučí tak, jak je?" Udělejte to nejlepší, pak pokračujte. If it’s not part of documented standards, prioritise the code author’s preferences. Remember that there is no such thing as perfect code: a quest for unattainable perfection leads to frustrated contributors and slow progress. Ask yourself “what’s the worst case scenario if this code gets merged as-is?” Do your best, then move on.



Promyšlená účinnost

 * Cílem srozumitelnosti: Ujasněte si, co považujete za blokátor, na rozdíl od věci preferencí nebo žádosti o vysvětlení. Vyvarujte se eufemismů a neúplných vět: Jasně uveďte, co máte na mysli a co si myslíte, že se musí stát. Ujasněte si, jak budou konflikty řešeny.
 * Poskytněte kompletní recenze: Prohlédněte si celý patch a při nejbližší příležitosti upozorněte na každý problém. Když je nahrána nová sada oprav, zkontrolujte pouze nové změny. Snažte se sloučit kód v co nejmenším počtu cyklů kontroly/odpovědi. Pokud se necítíte být zpočátku schopni poskytnout úplnou recenzi (např. pokud je kódová základna nebo programovací jazyk pro vás nový nebo u velmi složité opravy), zvažte nejprve diskusi o opravě s předkladatelem opravy.
 * ...a identifikujte, když nemůžete: Pokud se necítíte být schopni poskytnout úplný přehled, zvažte proč: Je to otázka zkušeností, zdrojů nebo sociální dynamiky? Pokud je kódová základna nebo jazyk pro vás nový nebo se jedná o velmi složitou opravu, zvažte nejprve diskusi o opravě s autorem opravy.
 * Zůstaňte soustředění: Patch by měl mít jeden nápad a jeho důsledky. Pokud v blízkém kódu uvidíte něco, co se vám nelíbí, ať už jako recenzentovi nebo vývojáři, udělejte si poznámku nebo zapište úkol, nepřidávejte do odevzdání další změny. Velké obrazové nebo architektonické diskuse by se měly odehrávat jinde.
 * Vyhněte se hnidopišství: Hroty jsou komentáře o menších, nedůležitých problémech, které odvádějí pozornost od konečného cíle recenze.
 * Dva vývojáři se stejným problémem zřídka napíší stejný kód. Respektujte kreativní rozdíly. Neopakujte práci vývojáře tím, že je požádáte, aby napsali přesný kód, který byste napsali. Kód prostě musí být přijatelný, nemusí být dokonalý.
 * Při psaní recenze se ujistěte, že se nezaměřuje na drobné problémy (jako je styl kódu).
 * Rámujte své komentáře jako užitečné tipy, nikoli chyby, které je třeba opravit. Označte hnidopichy jako takové a nedovolte jim, aby blokovaly sloučení.
 * Odpovídejte rychle: Kritická zpětná vazba je lepší, pokud je poskytnuta rychle a následuje rychlými odpověďmi na otázky nebo aktualizovaným kódem.
 * Automatizovat: Vše, co automatizujete (prostřednictvím testů, linterů a CI), již není při kontrole kódu zátěží. Automatizujte, jak jen můžete, a poznamenejte si opakované diskuse jako potenciální příležitosti pro automatizaci.



Odmítněte normalizovat toxické chování

 * Využijte své privilegium: Ať už bude mít jakoukoli formu, použijte autoritu, kterou máte, abyste pozvedl své spolupracovníky a napravil nebo odmítl toxické chování.
 * Návrat k hodnotám: Když uvidíte problém, upozorněte na něj a zálohujte jej odkazem na tyto hodnoty.
 * Učte se ze svých chyb: Všichni máme prostor k růstu – upřímně se omluvte a poučte se ze svých chyb, pak pokračujte.
 * Nepřizpůsobujte se toxické kultuře: Neměli bychom ztrácet čas hlídáním toho, kolik emotikonů nebo vykřičníků používáme. Místo toho bychom měli zpochybnit toxické kultury.
 * Získejte pomoc, když ji potřebujete: Kontaktujte správce projektu nebo odešlete zprávu výboru pro kodex chování.



Doporučená literatura

 * Soucitné kódování: Tajemství vysoce výkonných týmů
 * Odnaučení toxického chování v kultuře kontroly kódu
 * Deset přikázání programování bez ega
 * Jak vylepšit dobré recenze kódu
 * Průvodce všímavou komunikací v recenzích kódu
 * Konvenční komentáře
 * Nenásilná kontrola kódu
 * Sedm principů datového feminismu

Poděkování
Mnohokrát děkujeme všem, kteří poskytli nápady, zpětnou vazbu a zdroje, které přispěly k vytvoření těchto pokynů.