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ě. Komentáře "X je špatně" a "Uvažovali jste o Y?" mají velmi odlišné účinky.
 * 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.
 * Ask "what do you think?" and listen to the response.
 * 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ářů: 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í.
 * Nechte to: S grácií přijměte kompromis nebo porážku. 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.



Promyšlená účinnost

 * Aim for clarity: Be clear about what you consider a blocker as opposed to a matter of preference or a request for clarification. Avoid euphemisms and incomplete sentences: clearly state what you mean and what you think needs to happen. Make it clear how conflicts will be resolved.
 * Provide complete reviews: Review the entire patch and raise every issue at the earliest opportunity. When a new patchset is uploaded, review only the new changes. Aim to merge the code in the fewest number of review/response cycles. If you don't feel able to provide a complete review initially (e.g. if the codebase or programming language is new to you, or for a very complex patch), consider discussing the patch with the patch submitter first.
 * ...and identify when you can't: If you don't feel able to provide a complete review, consider why: is it a question of experience, resourcing, or social dynamics? If the codebase or language is new to you, or for a very complex patch, consider discussing the patch with the patch author first.
 * Stay focused: A patch should have one idea and its consequences. If you see something in nearby code that you don't like, either as a reviewer or developer, make a note or file a task, don't add more changes to the commit. Big picture or architectural discussions should happen elsewhere.
 * Avoid nitpicking: Nitpicks are comments about minor, unimportant issues that distract from the ultimate goal of the review.
 * Two developers, given the same problem, will rarely write the same code. Respect creative differences. Don't repeat the work of the developer by asking them to write the exact code you would have written. The code just needs to be acceptable, it doesn't need to be perfect.
 * When writing a review, ensure that minor issues (like code style) are not the focus.
 * Frame your comments as helpful tips, not faults to be rectified. Mark nitpicks as such and do not allow them to block merging.
 * Respond quickly: Critical feedback goes over better if it’s provided promptly and followed up with quick responses to questions or updated code.
 * Automate: Everything you automate (via tests, linters, and CI) is no longer a burden during code review. Automate as much as you can, and note repeated discussions as potential opportunities for automation.

Refuse to normalise toxic behaviour

 * Use your privilege: Whatever form it may take, use the authority you have to lift up your collaborators and correct or reject toxic behaviour.
 * Return to values: When you see a problem, point it out and back it up with a reference to these values.
 * Learn from your mistakes: We all have room to grow—apologize sincerely and learn from your mistake, then move on.
 * Don’t adapt to a toxic culture: We shouldn’t waste time policing how many emoji or exclamation points we use. Instead, we should question toxic cultures.
 * Get help when you need it: Contact the project maintainers or submit a report to the Code of Conduct Committee.

Recommended reading

 * Compassionate coding: The secret of high performance teams
 * Unlearning toxic behaviours in a code review culture
 * The ten commandments of egoless programming
 * How to make good code reviews better
 * A guide to mindful communication in code reviews
 * Conventional comments
 * Non-violent code review
 * The seven principles of data feminism

Acknowledgements
Many thanks to everyone who provided ideas, feedback, and resources that went into creating these guidelines.