Přejít k navigační liště

Zdroják » Různé » Commitujte jako profík!

Commitujte jako profík!

Články Různé

Commity a jejich popisky (commit messages) jsou často na okraji zájmu vývojářů. Přitom pokud se s nimi pracuje špatně, týmový vývoj často drhne a v průběhu historie projektu se zbytečně ztratí spousta užitečných informací. Pojďme se proto podívat, jak commity tvořit správně.

Nálepky:

Ten příběh asi znáte. Jako programátor jste nově přiřazen k projektu, který už nějakou dobu běží. Jako první úkol dostanete provést nějakou drobnou úpravu, do které se nikomu jinému nechce. Ponoříte se do kódu, ale nerozumíte jedné jeho části. Vidíte sice, co kód dělá, ale netušíte proč. Komentář žádný, kolegové krčí rameny, autor už ve firmě nepracuje.

Rozhodnete se tedy podívat do historie těch pár řádek ve verzovacím systému. Najdete commit, který je přidal, a zobrazíte ho. Místo očekávané drobné úpravy ale vyběhne diff přes pět obrazovek. Jeho popisek je lakonické „fixed few bugs“. Chvíli nevěřícně koukáte na obrazovku a pak zalitujete, že jste se místo programování radši nedali na fyziku, když vás ve škole tak bavila.

Commity

Prakticky každý software je dnes vyvíjen ve verzovacím systému. Základem takových systémů jsou commity – změny ve spravovaných souborech. Důležitou součástí commitu je jeho popisek (commit message).

Vytvářet dobré commity a správně je popisovat je – poněkud nečekaně – docela umění. Mnoho vývojářů to nedělá, ať už proto, že si nemyslí, že je to potřeba, nebo protože to neumějí. Výsledkem jsou příběhy jako náš úvodní a spousta ztraceného času a peněz.

Pokud jsou ale commity v projektu vedené dobře, stane se jejich historie časem cenným zdrojem informací nejen pro nováčky v týmu, ale i pro ostřílené vývojáře, kteří jen zapomněli, proč to či ono kdysi dělali. Hodnota těchto informací obvykle velmi rychle roste s časem a změnami v týmu a především u technicky složitých projektů poměrně brzo převýší náklady na jejich pořízení.

Snad ještě důležitější než hodnota historická je u commitů jejich hodnota kolaborační. Většina softwaru vzniká v týmu a commity jsou prostředkem, jak se vývojáři navzájem informují o své práci a můžou ji vzájemně revidovat a kontrolovat. Pokud jsou tvořené správně, ušetří se spousta času na dotazování a vysvětlování.

V pražské pobočce SUSE si času vývojářů ceníme a commity a jejich popisky se tak snažíme tvořit poctivě. Pokud máte rádi Linux a open source, přidejte se k nám.

Jak vypadá dobrý commit?

Základním pravidlem je, že jeden commit by měl řešit právě jeden problém – nikoliv jeho část a nikoliv víc problémů najednou. Commit by měl být atomickou jednotkou – před ním i po něm by kód měl být v konzistentním stavu.

Pokud commit řeší jen jeden problém, je mnohem jednodušší ho pochopit, než když je neúplný nebo řeší víc věcí. Je tak možné se lépe přesvědčit o jeho správnosti a nebo v něm naopak najít chyby. Pokud se nakonec ukáže, že nějaká změna není žádoucí, je také mnohem snazší vrátit zpět jeden specifický commit, než zjišťovat, která část většího commitu je relevantní, případně naopak které všechny commity s vracenou změnou souvisí.

Co je jeden problém?

Definice toho, co je jeden problém, je samozřejmě subjektivní a najít správnou míru chce cvik. Zkušenost říká, že vývojáři mají spíš tendenci tvořit commity příliš velké, než naopak (což je do značné míry dáno i neflexibilitou některých verzovacích systémů, které neumožňují commity snadno dělit). Moje rada tedy zní: pokud si nejste jistit správnou granularitou, přikloňte se spíš k více menším commitům, než naopak.

Co s problémy, které rámec jednoho commitu zjevně přesahují? Správný postup je rozdělit je na podproblémy a každý vyřešit samostatně. Výsledné commity je pak možné propojit např. pomocí prefixu v popisku:

User refactoring 1/5: Make permissions more detailed
User refactoring 2/5: Extract common code to a superclass
.
.
.

Konzistentní stav

Jak jsem již uvedl, před i po commitu by kód měl být v konzistentním stavu. To mimo jiné znamená, že daný kus softwaru se před commitem i po něm chová přesně stejně (krom věcí, které commit cíleně mění) a všechny testy po commitu stále běží. Jinými slovy, nemělo by se stávat, že jeden commit něco rozbije a další to pak spraví. Takový přístup neprospívá třeba continuous integration serverům (které mohou zachytit rozbitý stav a vyvolat planý poplach) a ani lidem (kteří mohou např. revertem commitu nechtěně vrátit kód do rozbitého stavu).

Jedním z důsledků pravidla o konzistentním stavu je, že pokud máte testy, měli byste je měnit spolu s kódem, se kterým souvisí.

Popisky

Důležitou součástí commitu je jeho popisek (commit message). Má dva hlavní cíle:

  1. Popsat provedenou změnu
  2. Vysvětlit, proč bylo potřeba ji provést

S prvním bodem obvykle problémy nejsou, navíc není tak důležitý, protože jen shrnuje informaci zřejmou z kódu. Zato druhý bod je často opomíjen.

Důvod změn v kódu je někdy zjevný (např. přidání nové funkcionality), jindy docela komplikovaný (např. je-li výsledkem dlouhé diskuze zvažující mnoho faktorů nebo několika hodin hledání chyby). Ve chvíli, kdy důvod změny není úplně zřejmý a vy ho nikde nepopíšete, prakticky vyhazujete úsilí, kterým jste k němu dospěli, z okna.

Představte si, že jste strávili dva dny tím, že jste hledali v kódu chybu. Když jste ji našli, přidali jste dva řádky s opravou. Po roce se stane, že někdo úplně jiný bude tuto část kódu kompletně přepisovat. Pokud z komentáře nebo z historie kódu nepochopí, proč tam ony dva řádky jsou, je docela možné, že je vypustí jako nejspíš zbytečné. Výsledek bude, že vaše práce přijde vniveč. Chyba se vrátí a někdo jiný opět stráví dva dny jejím hledáním a opravou. Přitom by stačilo, kdybyste strávili dvě minuty navíc napsáním popisku.

Commit je často součástí práce na vlastnosti či bugu, které jsou evidovány v nějakém externím nástroji (např. issue tracker). V tom případě je dobré v rámci popisku odkázat na příslušnou issue či jinou jednotku, se kterou tento nástroj pracuje. Čtenář tak bude mít přístup ke kontextu, ve kterém byl commit vytvořen. Takový odkaz v mnoha případech může nahradit zdůvodnění (samozřejmě je důležité, aby byl dostatečně stálý a po pár měsících nepřestal platit).

Někdy je naopak dobré napsat zdůvodnění přímo do kódu – jsou totiž případy, kdy bez něj kód nebude srozumitelný a prakticky každý čtenář by si tak musel zdůvodnění pracně dohledávat. Často se jedná o opravy obskurních chyb, workaroundy atd. I zde je dobré odkázat do externích nástrojů, má-li to smysl.

Jak psát dobré popisky?

Při psaní popisku je důležité si uvědomit, pro koho ho vlastně píšete. V první fázi je to především pro vaše kolegy, kteří sledují, co se v projektu děje, případně commity čtou a revidují. Později se jejich čtenáři stanou především vaši kolegové, kteří zjišťují, proč nějaký kus kódu vypadá tak, jak vypadá. Nejlepší způsob, jak napsat dobrý popisek, je zkusit se na chvíli vcítit do těchto rolí a uvědomit si, které informace, které vy teď máte, čtenáři nemají a budou jim chybět.

Z osobní zkušenosti můžu říct, že dobrý bič na psaní užitečných popisků je zavedení povinných vzájemných revizí commitů v rámci týmu. V situaci, kdy každý váš commit musí schválit některý z kolegů, se vám každá nejasnost nebo nepochopení vrátí v podobě dotazů a komentářů. Psaním špatných popisků tak neztrácí čas abstraktní čtenář někdy v budoucnu, ale vy právě teď. To je docela silná motivace.

Formální stránka popisků

Mnohé projekty mají na psaní popisků ke commitům detailní pravidla. Jejich dodržování je podstatné především při přispívání do různých open source projektů, kde obvykle netušíte, jaký workflow a jaké nástroje používají ostatní vývojáři. V interních projektech si často můžete dovolit být volnější.

Před prvním commitem je dobré zjistit, zda daný projekt nějaké takové zásady má, a pokud ano, dodržovat je. Pokud projekt zásady nemá, stojí za to si alespoň projít historii a přizpůsobit se obvyklému stylu.

Popisky v Gitu

Protože Git má mezi verzovacími systémy v současnosti výsadní postavení, zmiňme několik zásad užitečných pro psaní popisků pro něj (volně převzatých z článku Tima Popea).

Git dělí popisky na jednořádkové shrnutí a volitelné detaily, které mohou mít libovolný počet řádků. Obě části jsou oddělené prázdným řádkem. Mnoho nástrojů pracujících s Gitem detaily vynechá, pokud zobrazuje víc commitů najednou. Z toho plyne, že shrnutí je dobré psát tak, aby bylo samostatné a stačilo k pochopení, o čem commit je.

Popisek je nejlépe psát v přítomném čase. Shrnutí by mělo začínat velkým písmenem a nemělo by být ukončeno tečkou, detaily by měly být ve větách jako normální text. Tento formát je kompatibilní s popisky generovanými příkazy jako git merge nebo  git revert.

Délka textu shrnutí by neměla překročit 50–60 znaků, text detailů je nejlépe zalomit na 72 znacích. Obojí je důležité především pro kompatibilitu s různými nástroji a také GitHubem.

Příklady dobrých popisků

Na závěr si ukažme několik popisků z reálných open source projektů, které považuji za dobré a ze kterých si můžete vzít příklad. Pro jejich úplné pochopení je potřeba znát kód a architekturu příslušného projektu, ale i tak je ze všech zřejmé, co commit opravuje a proč. Poslední popisek slouží jako příklad, že jako zdůvodnění někdy stačí odkaz na externí zdroj.

V8

Fix bug in deletion of indexed properties

The delete operator always return true in case of indexed property. It
should return false if an indexed property can't be deleted (eg.
DontDelete attribute is set or a string object is the holder).

Contributed by Peter Varga <pvarga@inf.u-szeged.hu>

BUG=none
TEST=mjsunit/delete-non-configurable

Review URL: https://codereview.chromium.org/11094021
Patch from Peter Varga <pvarga@inf.u-szeged.hu>.

(Reference)

Chromium

Fix wrong truncation of notification popup messages in ash.

views::Label control first calculates the size of the text,
and then tries to render the text in the exact size of rectangle.
If < is used instead of <= in the patched line, the control
flows to the BreakIterator mode, that sometimes computes a
larger width value and causes truncation.

BUG=155663

Review URL: https://codereview.chromium.org/11150013

(Reference)

Google Closure Compiler

Attach types to literals at scope-creation time instead of at
inference time.

Scope-creation already attaches types to function literals at
scope-creation type, so this makes the other literals more consistent
with function literals.

R=johnlenz
DELTA=167  (102 added, 53 deleted, 12 changed)

Revision created by MOE tool push_codebase.
MOE_MIGRATION=209649

(Reference)

Rails

Move two hotspots to use Hash[] rather than Hash#dup

https://bugs.ruby-lang.org/issues/7166

(Reference)

Závěr

Práce s commity a jejich popisky je důležitější, než se na první pohled zdá. Pokud vám článek v tomto směru nedal nic nového, je to dobře – s commity nejspíš už pracujete správně. A pokud jste se naopak něco dověděli, zbývá jen nabyté znalosti aplikovat v praxi a hlavně předat všem spolupracovníkům, kteří commitují změny přes pět obrazovek popisem fixed few bugs

Komentáře

Subscribe
Upozornit na
guest
54 Komentářů
Nejstarší
Nejnovější Most Voted
Inline Feedbacks
View all comments
Michal
  • Prakticky každý software je dnes vyvíjen ve verzovacím systému.

No, tak to by se autor článku při střetu s realitou asi dost divil. Zejména když ten software není vyvíjen jako produkt, ale jen jako nějaký interní nástroj – byť obrovský a naprosto kritický pro chod firmy – to jsou pak k vidění různý hrůzný věci. Zvlášť vývojáři vychovaní mimo Open Source dost často vůbec o verzovacích systémech nemají ponětí.

Honza

Dělal jsem ve 4 firmách a viděl jsem dost různých hrůzných věcí (bezdůvodnou práci pod rootem, špagetový C kód, naprosto nečitelný C++ kód ve stylu, čím víc šablon a přetížených operátorů, tím lépe, totální nekomunikaci mezi kolegy, nekomentování, komentování getX() stylem „vrací X“, nucení vývojářů do nepoužitelného verzovacího systému, cholerického asociálního šéfa, sluníčko na monitoru, totálně neschopného programátora, atd. atd.) Ale nepoužití verzovacího systému na cokoli nezanedbatelného jsem ještě nezažil.

j

Ja jo, a opakovane, v pozici zakaznika sem pak neustale resil, ze sice upravili to co sem chtel, ale prestalo fungovat to, co se delalo minule, paac jako zaklad pro upravu pouzili neaktualni verzi …

arron

Ono asi záleží s čím zrovna přijdeš do styku…já jsem měl taky pocit, že používat SVN/GIT je tak normální jako že každý ráno zapnu počítač…až do té doby, kdy se mě kamarád (pracující ve firmě, která se zabývá webovými stránkami) zeptal na radu, že by jako chtěli zavést to esvéenko. Trochu se mi podlomila kolena…nicméně jsem se zeptal, jak to dělají teď a prý „se připojím na eftýpko a otevřu si to v pspadu.“ Tak to se mnou fakt málem švihlo :-D

5o

V tých firmách čo píšeš je to tak, že naberú študentov a oni robia jak vedia. Žiaden systém, menia ich ako ponožky. Proste čo najlacnejšie. Open source sa mi zdá úplne inak, ľudia si na tom dávajú záležať a neustále vymýšľajú nové veci a automatizujú. A hlavne vytvárajú prostredie pre ľudí, ktorých to baví a je to zadarmo. Paráda.

lenken

Ale tak to není, pokud by se opravdu dělalo na dvou, třech téměř interních projektech, tak to jde i tak krásně ulítle, jak to je psáno v článku. Je to krásný, ale normální lidi tak opravdu nemohou pracovat.

Ano, jde to s gitem či svn dobře (s gitem mnohem lépe), ale v množství projektů naskládaných za dlouhá léta (často stovky), je to problém – nelze jít revolucí, lze jít jen evolucí – ne všechny projekty mohou být ihned nahrány do repozitářů – je to práce na dlouhý měsíce či roky – ono se totiž musí i dále pro klienty pracovat.

Nehledě na studenty či nestudenty.

Martin Hassman

Zajímal by mě příklad takového projektu, který nemůžete jednoduše dát do verzovacího systému a proč.

nepodstatné

Pokud je projekt několik let zanešený nepořádkem(např. různými provozními soubory co se generují libovolně kam, tvrdým prolinkováním), tak to opravdu může trvat docela dlouho. Měsíce a roky se mi zdá přehnané, ale týden dva to vzít může – to mám z vlastní zkušenosti (i s nechápavostí nezasvěcených). Ale samozřejmě tato práce se vyplatí (opět z vlastní zkušenosti).

Franta <xkucf03/>

To je u řady webových studií standardní postup :-)

vbl

A nepoužívají na synchronizaci zdrojáků na FTP šindel?
http://thedailywtf.com/Articles/The-Source-Control-Shingle.aspx

Cermi

K čemu je mi popisek toho, proč je něco tak, jak je, v popisku commitu? Tohle má být v komentáři u toho „nestandardního“ kódu, kde to každý vidí hnedka a nemusí lézt do SCM. Navíc, pokud ten řádek někdo změní, tak funkce annotate/blame už nepřiřadí ten řádek k původnímu commitu, který obsahuje to vysvětlení. Mě osobně se osvědčilo mít v commitu krátký komentář, cca odpovídající názvu work itemu, který ten commit řeší (+ případné upřesnění, když 1 workitem řeším více commity) a veškeré detaily pak se nachází v tom work itemu (bug, task, …), na který vede odkaz z commitu (až už v popisku nebo nějak sofistikovaněji, pokud máme hezky propojené SCM a issue tracker). No a všechny netradiční nebo nezřejmá řešení (na které odkazuje autor článku) popíšu komentářem přímo v kódu, kde to zůstane. Důvody změny typu „zákazník to tak chce“ jsou zase evidentní z odkazu na work item v issue trackeru.

jos

> K čemu je mi popisek toho, proč je něco tak, jak je, v popisku commitu? Tohle má být v komentáři u toho „nestandardního“ kódu

protože komentáře zastarávají a obvykle je nikdo nečte a nakonec je člověk jako já smaže

> Navíc, pokud ten řádek někdo změní, tak funkce annotate/blame už nepřiřadí ten řádek k původnímu commitu, který obsahuje to vysvětlení.

přečti si dokumentaci svýho SCM, třeba v případě mercurialu tam najdeš:

$ hg help annotate
hg annotate [-r REV] [-f] [-a] [-u] [-d] [-n] [-c] [-l] FILE...

...

options:

 -r --rev REV              annotate the specified revision

> Mě osobně se osvědčilo mít v commitu krátký komentář, cca odpovídající názvu work itemu, který ten commit řeší

hmm, v projektu kterej hákuju (cca 350.000 řádků kódu / 35.000 revizí) by to znamenalo mít dalších 50.000 řádků s komentářema, super

neberu ti tvuj postup, ale prezentuješ ho ve smyslu „v článku sou nesmysly, muj postup je univerzální a jedinej správnej“

Honza

No, na obranu původního přispěvatele je třeba říct, že nepropagoval svůj postup jako jediný správný, spiš se ohradil proti tomu, že v článku je prezentován jako jediný správný postup s důvodem v popisu commitu.

Mně osobně vaše námitky nepřijdou relevantní: proč nepsat důvody do komentářů – protože ji nikdo nečte a vy je pak smažete. Nepřipadá vám na tom něco divného? Úplně stejně je to přece možné říct i obráceně: proč nepsat důvody do commitů? protože je nikdo nečte a smažu je zase já :-)

Prostě každému může vyhovovat něco jiného. Mne osobně připadá logičtější psát komentář do kódu. Když něco dělám, pracuju primárně s kódem a ten čtu/upravuju. Dohledávat ke každé části kódu, ke které se dostanu, commit s komentářem mi připadá zbytečně zdlouhavé.

Vaši stížnost, že ve velkém projektu by komentáře přidaly dalších 50000 řádek, což že je tragédie, bych pak neváhal zařadit mezi zvěrstva, popisovaná ve vlákně trochu výše. Protože nepsat do kódu komentáře s odůvodněním „bylo by to moc řádek navíc“ mi připadá ještě o úroveň prasečtější než nepoužívat verzovací systém.

Martin

„Vaši stížnost, že ve velkém projektu by komentáře přidaly dalších 50000 řádek, což že je tragédie, bych pak neváhal zařadit mezi zvěrstva, popisovaná ve vlákně trochu výše. Protože nepsat do kódu komentáře s odůvodněním „bylo by to moc řádek navíc“ mi připadá ještě o úroveň prasečtější než nepoužívat verzovací systém.“

+ 1

mchf

Proč nepsat zdůvodnění (jen) do komentářů? Protože když se pak fixuje kód tak je potřeba aktualizovat i komentář.

Fixoval jsem už pár řádek kódu, kde komentář byl následkem změn v kódu zcela irrelevantní. Což může trochu zamotat hlavu, takže vysvětlení ve správci verzí se může hodit.

j

Kdyz budu mit 10 radek kodu, kzdej z jinyho commitu, tak budu jak idiot dohledavat pro kazdej extra, proc ho tam nekdo dal? Nemluve o tom, ze to co je napsany v tom popisu muze byt kvuli zmenam kodu uz taky pekna kravina.

Ve verzovacim systemu ma bejt odkaz na bugreport/zada­ni/… a lehkej globalni koment co ze to ma delat, v kodu ma bejt popis detailu a predpokladam, ze pokud nekdo upravi kod, upravi nalezite i komenrare (jinak si zasouzi byt zastrelen).

Jerry12

S timhle popisem se ztotoznuju. Jeho dusledkem je i docela podstatnej detail. Pokud vezmu kod bez SCM a trackeru, tak porad mam informaci o tom co je kde a proc.

vks

Ideální stav je, když je kód samovysvětlující a komentáře jsou tam, kde jsou potřeba. U komitů je jasná reference (Id a popisující název) na bug/featuru, kde je popis problému, popis řešení a potvrzení o úspěšném otestování, či co se s tou prací nakonec stalo.

Veškerá historie se dá dohledat a anotací si člověk může snadno ukáže, kdo kdy kde co editoval.

Když budu mít 10 řádků kodu, každý z jiného komitu, tak si ten kód přečtu a pokud nebude dávat smysl, tak si projdu jednotlivé změny a když nebudou jasné, tak se začnu dívat do dokumentace k bugům/featurám… Podle svých kolegů jsem ještě málo otrlý, abych byl schopný skousnout bez použití sprostých slov, když smysl změn nejde odhalit ani po pročtení (často velmi zanedbané) dokumentace.

jos

> No, na obranu původního přispěvatele …

věc názoru, mě to tak přišlo

> Úplně stejně je to přece možné říct i obráceně: proč nepsat důvody do commitů? protože je nikdo nečte a smažu je zase já :-)

revize v centrálním repository? asi ne

zastaralejch komentářů sem viděl mnohem víc než těch aktuálních, takže názor jen tak nezměnim

> Protože nepsat do kódu komentáře s odůvodněním „bylo by to moc řádek navíc“ mi připadá ještě o úroveň prasečtější než nepoužívat verzovací systém.

IMHO kód bez komentářů je čitelnější, co dělá má bejt vyjádřený názvem jednotky ve který je; četbou kódu trávim velkou část pracovní doby, takže přirozeně chci aby to bylo co nejpříjemnější; naopak do historie zavítávam o dost míň často a SCM ty informace navíc unese

takže to odůvodnění není ‚nepsat do kódu komentáře s odůvodněním „bylo by to moc řádek navíc“‚, ale ‚nepíšu komentáře, protože je to balast kterej mě zdržuje od práce‘

udělat smysluplnej vysvětlující commitmessage je IMHO daleko lepší než psát komentář do kódu

Honza

> revize v centrálním repository? asi ne

Zálěží co používáte za verzovací systém. To, co máme my, umožňuje komentáře zpětně měnit. Hodí se, když je někdo napíše na poprvé špatně.

> udělat smysluplnej vysvětlující commitmessage je
> IMHO daleko lepší než psát komentář do kódu

Evidentně se tedy neshodneme. Já si myslím, že psát komentáře je správně a že komentář je součástí kódu, takže když někdo mění kód kolem, musí změnit i komentář, jinak je to prostě chyba, kterou je potřeba opravit. Omlouvat vytváření chybného kódu leností mi nepřipadá vhodné.

A že komentáře vadí čítelnosti kódu? Tak to asi spíš vypovídá o vaší schopnosti psát komentáře. Dobrý komentář samozřejmě naopak má čtení kódu usnadnit! Vždyť to je jeho primární úkol.

Nijak vám váš postup neberu. Pokud neumíte psát komentáře, klidně používejte místo toho poznámky ke commitu. Mně ale připadá lepší mít komentář v kódu.

jos

> má čtení kódu usnadnit

asi spíš pochopení než čtení, ten drobnej rozdíl je právě klíčovej

> Tak to asi spíš vypovídá o vaší schopnosti psát komentáře

komentáře psát asi umim, ale prostě to nedělam, resp. jo, ale tak jednou za měsíc

> Evidentně se tedy neshodneme

žádná tragédie, v pohodě

KarelI

> komentáře zastarávají
To by melo resit CR. Myslim si, ze kod by mel byt samovysvetlujici, pokud to opravdu nejde, pak teprv mit komentar, pripadne ID chyb apod. Po 8 letech SVN se to z nej taha blbe, pouzivam jako posledni moznost.

> je člověk jako já smaže
proc proboha?

> dalších 50.000 řádků s komentářema
Cemu to vadi? Delame na o 2 rady vetsim projektu a komentaru tam je umerne tomu nekolik megaradku. Jeste jsem nenarazil na to, ze by to nekomu vadilo.

jos

> To by melo resit CR.

ano, leckdo by na to mohl ale nahlížet jako na náklady navíc, commitmessage musim napsat tak jako tak

> Myslim si, ze kod by mel byt samovysvetlujici, pokud to opravdu nejde, pak teprv mit komentar, pripadne ID chyb apod.

naprostej souhlas

> proc proboha?

právě proto, že už nedávají smysl

> Cemu to vadi?

čitelnosti kódu

disposable

u nas sice pouzivame len SVN, ale ked editujem 30 roznych suborov a commitnem to, tak commit message by bol niekedy rovnako dlhy ako zmeny ktore som vykonal. Ked tak pozeram na historiu commitov, tak asi 30-40% commitov je robenych stylom svn commit -m „asdf“

arron

Možná mě za to budete kamenovat, ale komentáře jsou zlo!! Snažíme se pomocí nich v 90% případů dohnat to, co jsme nebyli schopní napsat kódem. Kód má být samovysvětlující (jak tu už bylo řečeno) a za normálních okolností by neměl vyžadovat komentář. Nenuťme čtenáře našeho kódu číst dvakrát to samé (jednou v kódu a jednou v komentáři). Existují samozřejmě vyjímky, kterými jsou geniální nápady (které obvykle vyžadují poněkud nestandardní přístup), doc komentáře (javadoc, phpdoc apod.), komentáře optimalizací (rychlostní, algoritmické), kde na první pohled nemusí být vidět co přesně děláme a proč, no a potom komentáře úmyslů (typicky //intensionaly == v php u ifu).

http://pavlix.net/

„Možná mě za to budete kamenovat, ale komentáře jsou zlo!!“

Kamenovat ne, protože zbytku svého komentáře stejně popíráš sám sebe.

„Existují samozřejmě vyjímky, kterými jsou geniální nápady (které obvykle vyžadují poněkud nestandardní přístup), doc komentáře (javadoc, phpdoc apod.), komentáře optimalizací (rychlostní, algoritmické)“

… komentáře hacků, které se v kódu používají z důvodu chyby jiného nástroje, z důvodu úmyslného porušení chybného standardu, aby software fungoval. Z důvodu
toho, že v kódu děláme něco překvapivého a není na první pohled zřejmé, proč.
Z důvodu, že nemůžeme očekávat, že další vývojáři a pozdější maintainer bude
rozumět danému konceptu. Z důvodu toho, že existuje někde na webu (v bugzille)
zdroj, na kterém je o dané chybě či problematice hromada dalších informací.
Pro doplnění typových informací.

A můžeš doplňovat další věci, na které jsou komentáře dobré.

arron

To co popisuji dále ve svém příspěvku (a Ty ve svém) je oněch 10% případů, kde ten komentář dává smysl, neduplikuje kód a tím se nestává bordelem, který je z kódu potřeba rychle smazat :-) Pro těch zbylých 90% napsaných komentářů si stojím za tím, že jsou zlem ;-)

Pavel Šimerda

„To co popisuji dále ve svém příspěvku (a Ty ve svém) je oněch 10% případů, kde ten komentář dává smysl“

Pokud komentáře používáš správně, tak je to 100%.

Karel

To je právě ten poměr komentářů k samotnému kódu, 10 ku 90 :-)

sachy

,,Kód má být samovysvětlující (jak tu už bylo řečeno) a za normálních okolností by neměl vyžadovat komentář. Nenuťme čtenáře našeho kódu číst dvakrát to samé (jednou v kódu a jednou v komentáři).“

Až si čuchnete k nějakému většímu projektu v assembleru, budete rád za každé slovo komentáře a při pohledu na eyecatcher (konstanta, která je dobře vidět v dumpu paměti) budete vrnět blahem.

Nox

Assembler je holt trochu odlišný jazyk, pro většinu souhlasím s tím, co dotyčný píše. I když občas sám píši zbytečné komentáře, konkrétně typu „nadpis“, protože je pak hezky barevně oddělený kód … ale to je taková osobní odchylka.

dejfson

myslim, ze byste se na to meli divat nejen z pohledu ajtaka. Ja bezne pouzivam SVN a mercurial na revize VHDL kodu. Tam se bez poradnych popisku neobejdete. Jeden z duvodu je napriklad, pokud vkladate nekam (do cipu) synchronizacni registry. Na prvni pohled je muzete z kodu vyradit, protoze zdanlive nic nedelaji. Pokud nenapisete poznamku primo do kodu a nevysvetlite proc to tam je, nekdo je drive nebo pozdeji vyradi.

u velkych projektu, navic pokud pracujete se studenty, jsou komentare v kodu esencialni zalezitost.

Sten

Hmm, komentáře jsou zlo a pak vypíšete pět důvodů, k čemu jsou komentáře dobré a kterými pokryje 90 % všech komentářů ;-)

KarelI

Jak pise autor clanku – je dobre commitovat nezavisle zmeny zvlast – commit co nejmensi, pak i komentar je docela kratky. Davat hromadne zmeny s asdf komentarem opravdu nedava moc smysl.

http://pavlix.net/

Nebo často místo třířádkové opravy musíš nebo chceš restrukturalizovat nějakých 200 řádků kódu a chceš popsat vedlejší efekty té změny, že :).

nobody

Myslim si ze pri vacsom projekte je celkom jedno kolko textu commit message obsahuje.
Myslim ze najdolezitejsie je aby sa message odkazovala do systemu kde je k danemu commitu pridelena uloha a mozno presne sledovat na zaklade coho bol dany commit spachany.

arron

Zrovna teď jsem četl zajímavý článek, který IMHO řeší spoustu problémů se kterými jsem se setkal. Hlavně ten, že ať jsem se snažil jak jsem se snažil, tak ve finále mi ten commit log v drtivé většine případů byl k ničemu :-)

http://arialdomartini.wordpress.com/2012/09/03/pre-emptive-commit-comments/

arron

„Představte si, že jste strávili dva dny tím, že jste hledali v kódu chybu. Když jste ji našli, přidali jste dva řádky s opravou. Po roce se stane, že někdo úplně jiný bude tuto část kódu kompletně přepisovat. Pokud z komentáře nebo z historie kódu nepochopí, proč tam ony dva řádky jsou“
a
„Někdy je naopak dobré napsat zdůvodnění přímo do kódu…“

Jestliže jsem napsal dva řádky kódu, kterým už po týdnu nikdo nerozumí, tak ty dva řádky stály za nic!! Buď je potřeba ten kód napsat tak, aby byl samovysvětlující a pokud to nejde (jedná se o nějakou hardcore tuning výkonu či nějakou geniální myšlenku, která něco zjednodušuje), tak si to zaslouží krátký vysvětlující komentář přímo v kódu. Pokud je to oprava chyby, tak je třeba na ní nejdříve napsat failující test a pak teprve napsat onu opravu. Jedině tak lze poměrně spolehlivě zajistit, že se taková chyba již nikdy nebude opakovat.

Čelo

V tomhle mne zaujal Commit(-message) Driven Development. Nejdřív napiš, co jdeš dělat, pak to udělej a až pak commitni.

Petr Blaho

Tom Pope je ve skutečnosti Tim Pope…. jen drobnost…

Ondrej Mikle

Malé commity kde jeden commit implementujíce jednu ‚věc‘ se hodí navíc při hledání s bisect (u gitu a Mercurialu). Najít konkrétní malý commit způsobující chybu je mnohem užitečnější než velký megacommit.

Ad. komentáře: stylem „self-explanatory code“ je možné psát možná nějaké malé kusy kódu. V čemkoli větším človek narazí na:

– Bug v závislé knihovně, kde není jiná možnost než to okomentovat („this does XYZ as a workaround for bug 1234 in libZaGreatThing“). Tam by byl jenom kód „self-deceiving“ a ne „self-explanatory“. Ani autor sám si takové věci nebude po pár měsících pamatovat.
– Jsou knihovny (třeba boost), které umožňují některé věci dělat elegantněji, ale to ještě neznamená, že kód bude na první pohled čitelnější, především pro někoho, kdo s boost zkušenosti nemá.

A hlavně:

High-level by měly být okomentovány třídy/metody/sou­bory něčím jako je doxygen/javadoc/e­pydoc. Pro někoho, kdo vidí kód prvý krát, to pomáhá vytvořit si představu, jak je udělaná architektura a API. Kód může být sebekrásnější, ale když ho je 2M řádek a má 10 závislých knihoven, na čtení je toho moc.

Už jenom taková drobnost jako jestli je za uvolnění paměti zodpovědný caller nebo callee dokáže sežrat spoustu času lovením po zdrojácích. Qt má asi jednu z nejlepších dokumentací, která se dá použít jako příklad (např. http://doc.qt.digia.com/4.8-snapshot/qstring.html)

Zástancem „OCD self-explanatory code“ je třeba Moxie Marlinspike (viz https://github.com/moxie0/Convergence/tree/master/server). Ale i v krátkém kódu se lze stratit, pokud člověk nezná podrobně závislé knihovny (u Convergence je to třeba používání Deferred – lze odhadnout jak ty callbacky fungují, ale „vědět přesně“ znamená vzít debugger).

Nejvíc chyb vzniká „kooperačním paradoxem“ – kdy jeden vývojář neví, jaké invarianty a předpoklady má funkce Fň, kterou napsal jiný vývojář (viz letošní CVE v openssl).

jviki

Doplnil bych, ze neni dobre michat smysl komentaru v kodu a commit message. Uz proto, ze kod by nemel o existenci SCM vedet (co me je po tom, ze nekdo pouziva SVN klienta, kdyz ja pouzivam Git SVN klienta).

Komentare v kodu mohou byt zlo, ale do kodu dle meho nazoru patri. Rozhodne se vyplati psat komentare napr. k rozhrani a to tak, aby ctenar byl schopen napsat test tohoto rozhrani overujici, ze je spravne implementovano (netvrdim, ze to v praxi vzdy jde/funguje/…). Rozhrani bez komentare je (teoreticky) naprosto nepouzitelne a vyzaduje provadet neco jako reverezni inzenyrstvi hadanim parametru (v praxi je to pochopitelne trochu jinak).

Do commit message rozhodne nepatri komentar kodu. Patri tam informace, ktera napovi pozdejsimu ctenari proc (okolnosti) tam ten kod byl pridan/odebran/pre­sunut/…, jestli souvisi s nejakymi dalsimi zmenami, muze se vyjadrit k vice zmenam na ruznych mistech. Dulezite je, ze se vztahuje na diff obsazeny v commitu. To se primo v kodu (komentarem) vyjadruje obtizne. O zastaravani komentaru ani nemluve (commit message nezastara, protoze je pevne spjata s kodem v case).

Taky se domnivam, ze commit nemusi nutne (ale mel by) nechat projekt v konzistentnim stavu. Pri vetsich zmenach to temer nelze provest, aniz by tim utrpela historie – bylo mozne se v tech zmenach zpetne vyznat. Pokud spolu vice commitu souvisi, mely by byt ve zvlastni tematicke vetvi, a ta by konzistenci mela zajistit (lze revertovat celou vetev). Mnoho commitu, se kterymi se setkavam, jsou v podstate nerozdelene vetve. Casto me v nich zajima jen mala cast (problem granularity), a ta se obtizne hleda ve shluku zmen. Vetev navic sama pridava onu souvislost mezi commity a tudiz neni nutne pridavat prefix (to zalezi…).

Uznavam, ze prispevek je spise teoreticky, ale me to priblizne takto prakticky funguje pomerne uspesne.

Diskobolos

Věci je třeba dělat pořádně. Pak komentář komitu neobtěžuje.

lobo

niekedy je clovek prekvapeny co vsetko najde v komentaroch
velmi caste
– don’t touch
– here be dragons
– nechytaj , lebo sa to cele doserie
– nefunguje, treba fixnut ( najcastjsie sa to vyskytuje s nejakym datumom komentu tak 5 rokov dozadu )

Mé oblíbené

TODO: FIXME!!!

Herbert

// if you see this part and you are NOT in XXX project, then
// you should be hung by your balls from the window for the greatest sin of Copy&Pasting..

Me

Připadá mi, že si autor plete dokumentaci kódu s dokumentací vývoje kódu. Co kód dělá a proč jsou někde dva řádky by mělo být dokumentováno v tom kódu, komentář v commitu bude dohledávat jen zoufalec když už si vůbec nebude vědět rady. Fakt, že jsem tam ty dva řádky přidal já a proč jsem je tam přidal by měl být v komentáři v commitu, aby ostatní, kteří na kódu právě spolupracují věděli, co (jaká funkce) se měnilo.

Netvorus

Nekteri lide by si tento clanek (tedy aspon nadpis) meli vytetovat na celo, aby si ho kazde rano mohli precist v zrcadle.

Chapu, ze ten, pro koho „projekt“ znamena dva mesice prace na nejakych webstrankach, asi vyznam clanku plne nedoceni. Ale jakmile „projekt“ ma sanci zit vice let (=> napr. KAZDY informacni system jakehokoliv druhu), spravne commit zpravy jsou proste povinnosti.

Vtloukali jsme to jednomu tymu, se kterym jsme spolupracovali na vyvoji jednoho informacniho systemu. Vsichni uznale pokyvovali, ze toto vyznam ma a ze to neni spanty napad. Bohuzel se to jaksi nechytlo a oni dale pouzivali ono hezke, „bugfix“, „Sprint5“, „asr“ pro commit do projektu se zkratkou asr, ci krasne minimalisticke „.“ (ano, tecka nekdy staci). Bohuzel, nepouzivali ani zadny issue tracker, takze z commitu nebylo na co odkazovat (na papirek na scrum boardu budete tezko odkazovat ze…). Proste hruza, hruza, hruza… za par let budou s prominutim v prdeli. Uz ted (po pouhych dvou letech) jsem musel jednu cast kodu proste smazat/prepsat, protoze: 1. z kodu nebylo zrejme proc to dela (opravdu ne!) 2. v kodu nebyl zadny komentar 3. neexistoval aut. test 4. commit message neobsahoval v podstate nic 5. prislusny clovek ve firme uz nepracuje 6. zadny odkaz na todo/issue/feature request….

Takze moje zkusenost: cim vic komentaru (v kodu, commitu, nebo u issue) tim lip.

Jakub Vrána

Ve Facebooku je povinnou součástí commit zpráv také způsob otestování. Překvapuje mě, že to v článku není zmíněno. Někdy bohatě stačí vyplnit arc unit (spuštění dotčených testů), ale mnohem častěji se tam píše, jaká URL jsem navštívil a co jsem na nich udělal. Někdy se hodí tam dát i screenshot. Zdaleka ne všechny změny jsou totiž automatickými testy pokryté a ani si nemyslím, že by měly být pokryté. Když přidám na nějakou stránku odkaz, tak by v popisku mělo být napsané, že jsem navštívil danou stránku, na odkaz kliknul a dostal se na požadovanou stránku. Zdá se to samozřejmé, ale docela dost lidí to kupodivu neudělá („To je přece jasné, že tam ten odkaz bude, proč bych to kontroloval?“). Tahle maličkost kvalitu kódu podle mě výrazně zlepšuje. Někdy taky udělám nějakou změnu a tohle políčko mě donutí se zamyslet nad tím, jak bych ji měl vlastně správně otestovat. Příklad dobrého testu.

Další věc, která je v některých commit zprávách zásadní, je, jak jsem danou změnu udělal. To se zdaleka netýká všech commitů, ale např. refaktoringu, hromadných změn a podobně. Jaké nástroje jsem použil? Napsal jsem si na to nějaký skript? Jak jsem ověřil, že jsem změnil všechna místa, která změnu potřebují? Jak zajistím, že budoucí commity založené na kódu před změnou (a následně rebasenuté) nezavlečou starý kód zpátky (někdy je potřeba skript aplikovat za nějaký čas znovu)?

Jakub Vrána

Hlavní smysl commit zpráv vidím v odkazu budoucím generacím. Jak způsob testování, tak způsob provedení změn považuji za důležitou součást tohoto odkazu. Proto mě trochu překvapuje, že upřednostňuješ jiné věci (méně byrokracie, pečlivější review).

Enum a statická analýza kódu

Mám jednu univerzální radu pro začínající programátorty. V učení sice neexistují rychlé zkratky, ovšem tuhle radu můžete snadno začít používat a zrychlit tak tempo učení. Tou tajemnou ingrediencí je statická analýza kódu. Ukážeme si to na příkladu enum.