TakéCoding conventions, Code style, Coding style, Style guidePokročilý
Definice
Coding standard je sada domluvených pravidel, podle kterých tým píše, formátuje a strukturuje zdrojový kód. Určuje například pojmenování proměnných, odsazení, rozdělení souborů, komentáře nebo bezpečné idiomy, aby byl kód čitelný, konzistentní a snadněji kontrolovatelný napříč projektem, editory i revizemi v pull requestech.
Co coding standard rozhoduje v týmu
Coding standard dává týmu společný jazyk pro psaní kódu. Neřeší, co má aplikace umět, ale jak má vypadat a jaké vzory má používat její implementace. Typicky stanoví pojmenování tříd a funkcí, odsazení, délku řádků, organizaci importů, práci s výjimkami, komentáře, strukturu testů a někdy i zakázané konstrukce.
Dobrý standard zmenšuje počet drobných sporů v code review. Místo diskuse o tom, jestli má být závorka na dalším řádku, se reviewer soustředí na chování programu, datový model nebo dopady změny. Coding standard také pomáhá novým lidem, protože snižuje počet lokálních zvyků, které se musí naučit po nástupu do projektu.
Styl není jen odsazení
Coding standard bývá nejsnáze vidět na formátování, ale jeho cennější část je často sémantická. Projekt může například vyžadovat, aby veřejné funkce měly jednoznačný návratový typ, aby chybové stavy nepřecházely mlčky, nebo aby se dotazy do SQL neskládaly z řetězců. Takové pravidlo už není kosmetika, protože ovlivňuje spolehlivost, bezpečnost i budoucí údržbu.
Rozumný standard rozlišuje mezi pravidly, která lze opravit automaticky, a pravidly, která vyžadují úsudek. Formátování má patřit nástroji, například formatteru nebo linteru. Rozhodnutí, jestli je funkce příliš obecná nebo jestli název zavádí, zůstává na lidech.
Dva příklady z praxe
Frontend tým sjednotí pojmenování událostí
Frontend tým v React aplikaci používá směs názvů SubmitForm, submit_form a handleSubmit. Coding standard stanoví, že handlery událostí začínají slovem handle a používají camelCase. Pull requesty se potom čtou rychleji, protože vývojář podle názvu okamžitě pozná roli funkce.
function handleSubmit(event) {
event.preventDefault();
saveProfile(formData);
}Backend zakáže skládání SQL řetězců
Backend tým má v pravidlech, že uživatelský vstup nesmí být vložen přímo do SQL dotazu. Reviewer při kontrole odmítne změnu, která skládá dotaz interpolací, a požádá o parametrizovaný zápis. Výsledek není jen jednotnější styl, ale také menší riziko injekce.
cursor.execute(
"SELECT * FROM users WHERE email = %s",
(email,)
)Prosazení v běžném workflow
Coding standard funguje nejlépe, když je zapsaný v repozitáři a napojený na nástroje. Formatter může běžet při uložení souboru, linter před commitem a kontrola v CI před sloučením změny. Pravidla by měla být stejná lokálně i na serveru, jinak tým ztrácí důvěru v automatické výsledky.
Dokument nemá být encyklopedie všech preferencí. Krátký standard s několika tvrdě vynucenými pravidly bývá užitečnější než dlouhý text, který nikdo nečte. Výjimky mají být vzácné, pojmenované a zdůvodněné v kódu nebo v rozhodovacím záznamu.
Kde se coding standard mění v přítěž
Příliš přísný coding standard může brzdit práci, když vyžaduje ruční úpravy bez přínosu nebo když ignoruje idiomy jazyka. Standard pro Python nemá kopírovat pravidla z Javy a pravidla pro embedded C se budou lišit od pravidel pro webový frontend. Kvalitní tým pravidla pravidelně upravuje podle zkušeností, změn jazyka a nástrojů.
Příklady z praxe
Sjednocení názvů handlerů
Frontend tým v React aplikaci sjednotí názvy handlerů událostí na tvar handleSomething. Při code review už nikdo neřeší, jestli má funkce začínat velkým písmenem nebo používat podtržítka. Změny jsou čitelnější a nové komponenty zapadají do zbytku projektu.
function handleSubmit(event) { event.preventDefault(); saveProfile(formData); }Zákaz skládání SQL z řetězců
Backendový standard zakáže vkládání uživatelského vstupu přímo do SQL řetězce. Pull request se skládáním dotazu interpolací neprojde a autor použije parametrizovaný dotaz. Pravidlo zlepší konzistenci i bezpečnost kontroly vstupů.
cursor.execute( "SELECT * FROM users WHERE email = %s", (email,) )
Časté omyly
- MýtusCoding standard je jen o mezerách a závorkách.
- Ve skutečnostiCoding standard často zahrnuje formátování, ale tím nekončí. Užitečná pravidla mohou řešit práci s chybami, bezpečné idiomy, názvy veřejných API nebo strukturu testů.
- MýtusKdyž máme seniorní vývojáře, coding standard nepotřebujeme.
- Ve skutečnostiSeniorní vývojáři mohou mít velmi rozdílné zvyky. Coding standard neslouží jako náhrada odbornosti, ale jako společná dohoda, která šetří čas při review a onboarding nových členů týmu.
Časté dotazy
- Co má coding standard v projektu obsahovat?
- Coding standard má řešit pravidla, která se v týmu opakovaně objevují při psaní a kontrole kódu. Typický obsah zahrnuje formátování, pojmenování, strukturu souborů, importy, komentáře, práci s chybami, testovací konvence a zakázané konstrukce. Architektonická rozhodnutí do něj patří jen tehdy, když mají podobu jednoduchého, opakovatelného pravidla.
- Jak podrobný má být coding standard?
- Coding standard má být dost konkrétní na automatickou kontrolu tam, kde je to možné, ale nemá popisovat každou estetickou preferenci. Příliš volný dokument nepomůže při review, příliš podrobný dokument se rychle stane překážkou. Praktické měřítko je jednoduché: pravidlo má odstranit častý problém, ne jen prosadit osobní vkus jednoho vývojáře.
- Stačí používat formatter místo coding standardu?
- Coding standard a formatter se doplňují. Formatter automaticky upraví mezery, zalomení řádků nebo pořadí některých prvků, zatímco coding standard definuje širší očekávání týmu. Standard může říkat, že projekt používá konkrétní formatter, ale také řeší věci, které nástroj neumí bezpečně rozhodnout, například názvy doménových objektů nebo pravidla pro chybové stavy.
- Proč je coding standard důležitý u open source projektu?
- Coding standard v open source projektu usnadňuje přijímání příspěvků, protože externí autor ví, jak má změna vypadat ještě před odesláním pull requestu. Veřejný standard také snižuje práci maintainerů, kteří nemusí opakovaně vysvětlovat stejné připomínky. Největší přínos vzniká, když jsou pravidla krátká, ověřitelná a doplněná automatickou kontrolou.
Zdroje
- PEP 8 – Style Guide for Python Code(otevře se v novém okně)
- C# Coding Conventions(otevře se v novém okně)
- Linux kernel coding style(otevře se v novém okně)
- GNU Coding Standards(otevře se v novém okně)
Související pojmy
