Komentáře k článku

Commitujte jako profík!

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ě.

Zpět na článek

54 komentářů k článku Commitujte jako profík!:

  1. Michal

    Re: Commitujte jako profík!

    • 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í.

    1. Honza

      Re: Commitujte jako profík!

      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.

      1. j

        Re: Commitujte jako profík!

        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 …

    2. arron

      Re: Commitujte jako profík!

      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

      1. 5o

        Re: Commitujte jako profík!

        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.

        1. lenken

          Re: Commitujte jako profík!

          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.

          1. Martin Hassman

            Re: Commitujte jako profík!

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

            1. nepodstatné

              Re: Commitujte jako profík!

              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).

  2. Cermi

    Popisek důvodů v commitu?

    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.

    1. jos

      Re: Popisek důvodů v commitu?

      > 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“

      1. Honza

        Re: Popisek důvodů v commitu?

        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.

        1. Martin

          Re: Popisek důvodů v commitu?

          „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

        2. mchf

          Re: Popisek důvodů v commitu?

          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.

          1. j

            Re: Popisek důvodů v commitu?

            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).

            1. Jerry12

              Re: Popisek důvodů v commitu?

              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.

            2. vks

              Re: Popisek důvodů v commitu?

              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.

        3. jos

          Re: Popisek důvodů v commitu?

          > 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

          1. Honza

            Re: Popisek důvodů v commitu?

            > 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.

            1. jos

              Re: Popisek důvodů v commitu?

              > 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ě

      2. ijacek

        Re: Popisek důvodů v commitu?

        > 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.

        1. jos

          Re: Popisek důvodů v commitu?

          > 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

      3. disposable

        Re: Popisek důvodů v commitu?

        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“

        1. arron

          Re: Popisek důvodů v commitu?

          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).

          1. http://pavlix.net/

            Re: Popisek důvodů v commitu?

            „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é.

            1. arron

              Re: Popisek důvodů v commitu?

              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 ;-)

              1. Pavel Šimerda

                Re: Popisek důvodů v commitu?

                „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%.

          2. sachy

            Re: Popisek důvodů v commitu?

            ,,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.

            1. Nox

              Re: Popisek důvodů v commitu?

              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.

          3. dejfson

            Re: Popisek důvodů v commitu?

            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.

          4. Sten

            Re: Popisek důvodů v commitu?

            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ářů ;-)

        2. ijacek

          Re: Popisek důvodů v commitu?

          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.

    2. David MajdaAutor příspěvku

      Re: Popisek důvodů v commitu?

      Jen bych upozornil, že jsou případy, kdy v kódu není kam komentář napsat. Třeba proto, že změna zahrnuje mnoho souborů a není jedno centrální místo, kde by komentář měl smysl. Nebo proto, že commit nějaký kód/funkcionalitu maže (příklad). Pak je dobré důvod změny někam zaznamenat.

      Jinak souhlasím, že odkaz do bug trackeru apod. často stačí, ostatně v článku to celkem jasně píšu. Problém je, že ne ke všem projektům verzovaným v nějakém systému existuje bug tracker (já mám třeba na disku spoustu různých nikde nezveřejněných zdrojáků a skriptů, ke kterým žádný tracker nemám, ale v důvodech změn chci mít jasno). I pokud tracker existuje, ne každá změna v kódu musí být nutně asociovaná s nějakou issue – často by to byla jen byrokracie navíc. Pak se dobrý commit message hodí.

      1. http://pavlix.net/

        Re: Popisek důvodů v commitu?

        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 :).

  3. nobody

    Commit

    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.

  4. arron

    Komentář kódu v commitu?

    „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.

  5. Čelo

    Commit(-message) Driven Development

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

  6. Ondrej Mikle

    git bisect/hg bisect; high-level docs

    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).

  7. jviki

    Re: Commitujte jako profík!

    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.

  8. lobo

    komentare

    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 )

    1. Herbert

      Re: komentare

      // 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..

  9. Me

    Pletení

    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.

  10. Netvorus

    Svata pravda

    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.

  11. Jakub Vrána

    Otestování

    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)?

    1. David MajdaAutor příspěvku

      Re: Otestování

      O popisu způsobu testování v commit message se v článku nezmiňuju, protože o tom teď od tebe slyším poprvé. Přijde mi to nicméně jako docela dobrý nápad.

      V týmu SUSE Studia tohle částečně řešíme při review – u lidí, o kterých vím, že nejsou moc pečliví, třeba napíšu něco jako „LGTM assuming all unit tests are still running and you verified the UI manually“. Pokud to neověřili před pushem, nejspíš to udělají teď. Celé je to na jednu stranu oproti zmínce v commit message o něco neefektivnější, na druhou stranu, u lidí, kteří jsou pečliví, si poznámku odpustím a oni nemusí nikam nic psát, takže se ušetří něco byrokracie.

      U skriptovaných změn apod. souhlasím s popsáním způsobu provedení, ale třeba u hledání všech výskytů si myslím, že je naopak lepší, když přesný způsob vyhledání autor neuvede. Reviewer (pokud je pečlivý) si totiž výskyty taky zkusí nezávisle najít, možná použije jiný způsob a může tak přijít na to, že autor commitu něco minul. Pokud by v commit messge bylo rovnou napsáno, že autor použil ack -a 'foo', reviewer k tomu dost možná sklouzne taky a chybu tak nemusí odhalit.

      1. Jakub Vrána

        Re: Otestování

        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).

        1. David MajdaAutor příspěvku

          Re: Otestování

          Způsob provedení nebo otestování mě zpětně skoro nikdy nezajímaly, typicky se pídím především za důvodem změny. Myslím, že podobně to mají i jiní. Za „důležitou součást odkazu“ je tedy nepovažuju, je to spíš jen doplňující informace.

          Je jeden případ, kdy má způsob provedení smysl detailněji popisovat – když je netriviální a je možné až pravděpodobné, že něco podobného bude potřeba udělat znovu. Pak to v budoucnu může ušetřit práci. Ale to je pár případů do roka (alespoň u projektů, na kterých pracuju).

          U povinného popisu způsobu otestování chápu, že je to dobrý trigger pro zamyšlení, a taky může pomoct při review. Konec konců jsem psal, že to je dobrý nápad. Ale na druhou stranu, když si vezmu své commity, tak typicky upravují kód pokrytý unit testy, kde je alespoň jeden způsob otestování zřejmý, a nebo něco s vlivem na UI, kde je jasné, že jsem to proklikal. Psát do 99 % commitů „ran unit tests“ nebo „clicked though the UI“ je z mého pohledu zbytečná byrokracie. To 1 % za to tu povinnost nestojí. Opět, je to jen má zkušenost, jiní můžou mít odlišnou.

          Dá se samozřejmě namítnout, že já možná s testováním problém nemám, ale jiní mít budou a netestují adekvátně. Moje zkušenost je, že to není velký problém a pokud je, holt je potřeba být přísnější u review a dotyčného „vycvičit“. Pořád mám pocit, že je to v součtu méně práce, než povinná zmínka v commitu pro všechny.

Napsat komentář

Tato diskuse je již příliš stará, pravděpodobně již vám nikdo neodpoví. Pokud se chcete na něco zeptat, použijte diskusní server Devel.cz

Zdroj: https://www.zdrojak.cz/?p=3734