Zamyšlení nad komentováním kodu
- Lweek
- Člen | 12
Zdravím!
Nechci znít jako hnípal, ale rád bych se podělil. Trochu mi na Nette vadí způsob jakým se komentuje kod. Tedy ne samotný obsah komentářů, to bych si nedovolil jakkoliv hodnotit, ale spíš zlozvyk používat incode komentáře k popisu kodu.
Co mám na mysli.
Když mám někde nepohodlný kod který potřebuju z jakéhokoliv důvodu vyřadit, pak k tomu slouží
/* multiline code disabler */
nebo
// single line code disabler
K popisu kodu ale slouží spíš mřížka # nikoliv disabler //
Na funkcionalitu zahradníka to nemá vliv, ale na čitelnost kodu ano.
Ukázka
<?php
function foo()
{
// tohle je bla
// $this;
// $that;
// $those;
}
?>
Nebo
<?php
function bar()
{
# tohle je bla
// $this;
// $that;
// $those;
}
?>
Ani
<?php
function drink()
{
// tohle je bla
/* $this;
$that;
$those;*/
}
?>
mi nepřijde jako šťastná varianta.
Mimochodem většina editorů v dnešní době umožňuje zakomentovat nepohodlný kod pomocí CTRL+/ resp. CMD+/ pod MACem.
Je mi jasné, že po mě asi budete házet kamením a vykřikovat že „to je přece jedno, neřeš blbosti“, ale já pevně věřím že různé možnosti komentovat kod nevznikli úplnou náhodou a že to smysl má. Denně se přehrabuji v hromadě starého nahuštěného kodu, tak ten rozdíl vnímám víc než je to vidět u řidšího celkem úhledného MVC kodu.
- 22
- Člen | 1478
Přiznám se bez mučení, že termín single line code disabler
slyším prvně. Myslím, že ten #
vs. //
vyjde tak
nějak nastejno, když víc zařádkuješ. Nehledě na to, že //
je opravdu krátký jednořádkový komentář a co metoda dělá je zapsáno
nad metodou v phpDOC syntaxi, která ani hash nepoužívá snad.
/**
* A data bound list control that displays the items from data source in a table.
* The DataGrid control allows you to select, sort, and manage these items.
*
*/
function drink()
{
// tohle je popis
/*
$this;
$that;
$those;
*/
}
- Lweek
- Člen | 12
To není termín, spíš jen obrat v AJ, je to to přece cool. :)
Ano, popisování metod, objektů apod se řídí phpDoc syntaxí. In-code komentování žádný evidentní standard nemá, a to je problém. Ale existuje řada důvodů proč se nad komentováním kodu zamyslet.
Například, když je třeba kod upravovat v editoru bez zvýrazňovače syntaxe. Rázem je situace jiná. Zvláště v opravdu nahuštěném kodu.
příklad
<?php
dasdasfasfsafasdvcxzvxcgbtyr5tgdgf
dasdasfaafasdvcxzvxcgbtyr5tgdgf
dasdasfasfsafasdvcxzvxcgbtyr5tgdgf
dasdasfasfsafasdvcxzvxcgbtyr5tgdgf
/*dasdasfasfsafasdvcxzvxcgb5tgdgf
dasdasfasfsafavcxzvxcgbtyr5tgdgf
dasdasfasfsafavcxzvxcgbtyr5tgdgf
dasdasfasfsafasdvcxzvxcgbtyr5tgdgf
dasdasfasfsafasxzvxcgbtyr5tgdgf*/
dasdasfasfsafasdvcxzvxcgbtyr5tgdgf
dasdasfasfsafasdvcxzvxcgbtyr5tgdgf
dasdacxzvxcgbtyr5tgdgf
dasdasfasfsafasdvcxzvxctyr5tgdgf
?>
versus
<?php
dasdasfasfsafasdvcxzvxcgbtyr5tgdgf
dasdasfaafasdvcxzvxcgbtyr5tgdgf
dasdasfasfsafasdvcxzvxcgbtyr5tgdgf
dasdasfasfsafasdvcxzvxcgbtyr5tgdgf
// dasdasfasfsafasdvcxzvxcgb5tgdgf
// dasdasfasfsafavcxzvxcgbtyr5tgdgf
// dasdasfasfsafavcxzvxcgbtyr5tgdgf
dasdasfasfsafasdvcxzvxcgbtyr5tgdgf
dasdasfasfsafasxzvxcgbtyr5tgdgf
dasdasfasfsafasdvcxzvxcgbtyr5tgdgf
dasdasfasfsafasdvcxzvxcgbtyr5tgdgf
dasdacxzvxcgbtyr5tgdgf
dasdasfasfsafasdvcxzvxctyr5tgdgf
?>
V druhém případě si myslím, že zcela bez přemýšlení poznáte které řádky jsou vyřazené.
Dále proč rozlišovat pomocné komentáře od vyřazeného kodu? No třeba proto, aby je bylo možné vizuálně, ale i strojově odlišit, a zároveň aby nerušili.
<?php
dasdasfasfsafasdvcxzvxcgbtyr5tgdgf
dasdasfaafasdvcxzvxcgbtyr5tgdgf
dasdasfasfsafasdvcxzvxcgbtyr5tgdgf
// dasdasfasfsafasdvcxzvxcgbtyr5tgdgf
// dasdasfasfsafasdvcxzvxcgb5tgdgf
// dasdasfasfsafavcxzvxcgbtyr5tgdgf
// dasdasfasfsafavcxzvxcgbtyr5tgdgf
dasdasfasfsafasdvcxzvxcgbtyr5tgdgf
dasdasfasfsafasxzvxcgbtyr5tgdgf
dasdasfasfsafasdvcxzvxcgbtyr5tgdgf
dasdasfasfsafasdvcxzvxcgbtyr5tgdgf
dasdacxzvxcgbtyr5tgdgf
dasdasfasfsafasdvcxzvxctyr5tgdgf
?>
versus
<?php
dasdasfasfsafasdvcxzvxcgbtyr5tgdgf
dasdasfaafasdvcxzvxcgbtyr5tgdgf
dasdasfasfsafasdvcxzvxcgbtyr5tgdgf
# dasdasfasfsafasdvcxzvxcgbtyr5tgdgf
// dasdasfasfsafasdvcxzvxcgb5tgdgf
// dasdasfasfsafavcxzvxcgbtyr5tgdgf
// dasdasfasfsafavcxzvxcgbtyr5tgdgf
dasdasfasfsafasdvcxzvxcgbtyr5tgdgf
dasdasfasfsafasxzvxcgbtyr5tgdgf
dasdasfasfsafasdvcxzvxcgbtyr5tgdgf
dasdasfasfsafasdvcxzvxcgbtyr5tgdgf
dasdacxzvxcgbtyr5tgdgf
dasdasfasfsafasdvcxzvxctyr5tgdgf
?>
- Ondřej Mirtes
- Člen | 1536
Já bych byl drsnější. Pokud nějaký kód potřebuju vyřadit, tak ho smažu. Máme Git.
- Lweek
- Člen | 12
Ondřej Mirtes: to je pravda, ale zakomentování bloku pomocí CTRL+/ a přidání značky je rychlejší a produktivnější kor pokud se člověk například hrabe v cizím kodu. Než to prostě odmazat a pak to složitě hledat v repository a vracet zpět do aktuální kopie, tak to raději zakomentuji a po čase před nahráním do repository odmažu (třeba strojově).
22: Právě že ne, pokud máš lienární kód, pak ano, ale tam ti nepomůže ani svěcená voda. Jakmile má kod alespoň nějaké odsazení, pak věř že to poznáš protože ti ty komentáře budou tvořit vizuélní značku která bude jakoby vyčnívat.
Ještě bych se zmínil o jedné parádě. Když se zakomentovává pomocí CTRL+/ tak editor chytře nenarušuje ident. Navíc stejně jako se zakomentovává, tak se dá potom i odkomentovat – je to v podstatě jeden hmat. Když jsem se to před časem naučil, výrazně mi to zrychlilo a zpohodlnilo práci. Nejvíc to člověk ocení když je ve spěchu.
- na1k
- Člen | 288
Promiňte, jestli vám přijdu hloupější než syn vesnického idiota a televizní rosničky, ale pokud procházím kód (svůj či cizí) a chci něco dočasně zakomentovat, použiju přeci Ctrl+/, které přidá nějaké komentovací značky a ty samé po opětovném stisku zase odmázne. Může mi tedy být jedno, jestli dotyčný komentuje tak či onak, jestli radši lomítka anebo mřížky, což?
Osobně jsem komentování mřížkou v PHP nikdy nepřišel na chuť. Snad je to tím, že ostatní jazyky mřížkové komentáře nepoužívají, ale používám klasicky hvězdičky na phpDoc a lomítka na komentáře v kódu. Potřebu mřížek nemám a popravdě mi jejich zavádění (například skrze coding standards) přijde až kontraproduktivní.
Co takhle dělat něco užitečnějšího?
- Lweek
- Člen | 12
22: na MACu mě to funguje všude, pod Windows to mám ověřené pouze v Netbeans.
na1k: samozřejmě. O co mi jde je rozlišit komentování a zakomentování. Jestli si rozumíme. Zakomentováním myslím vyřazení kodu, komentáře myslím takové to jednořádkové povídání v kodu které má ujasnit co se v kodu děje. Pokud člověk píše dobře, tak nejsou vůbec potřeba – kod je samopopisný. Ale jsou chvíle kdy je kod zkrátka velice složitý nebo obsáhlý.
Já potom komentuju tak že odděluji jednotlivé funkční bloky. Asi takto:
<?php
/**
* Prevlecen za agenta FBI desim nevitane navstevniky
*
* @visibility public
* @return void
*/
function booToUnwantedVisitors()
{
# zjistim IP nastevnika
$visitorIP = $_SERVER['REMOTE_ADDR'];
# vydesim navstevnika
echo 'Tady FBI, tve IP je: ', $visitorIP, '!';
// echo 'Delam si srandu';
# jeste casova znamka
echo 'Dnes je: ', date('H:i d.m.Y', time());
}
?>
- hAssassin
- Člen | 293
@Lweek > ja ti rozumim jak to myslis, ale moc se
mi to nelibi… Dalsi „zbytecny“ znak do kodu. A vubec, ma zustat v kodu
nejaky zakomentovany kod, ktera tam nema co delat? Pokud opravdu neco zkousim a
potrebuju neco zakomentovat, tak /**/
nebo //
placnu
na zacatek radku jak rikas, ale ostatni inline komentare komentuju normalne
s prislusnym odsazenim //
.
Sorry, ale jak rika na1k, pojdme delat neco uzitecnejsiho ;-)
@22 > z toho si nic nedelej, me taky :-D a ani nevim jestli bych to nekdy pouzil
- arron
- Člen | 464
Tohle ale neni uplne blba poznamka:-) Nicméně já bych byl ještě daleko drsnější. Až na vyjímky totiž komentář do kódu nepatří! Takže, když něco ladím a potřebuju to na jeden či dva requesty zakomentovat, tak je mi uplně jedno, jakymi znaky to udělám a jak to bude vypadat. Důležité je, že před každým commitem všechny zakomentované řádky smažu, protože v kódu nemají co dělat a stávají se ‚zombie‘ řádky, které pak v kódu přetrvávají celá léta, protože nikdo nemá odvahu je smazat (a autor na to vždy úspěšně zapomene) a jsou jenom matoucím balastem. Pokud je potřebuju zpět, mám nějaký verzovací systém (a pokud nemám, tak je to moje vlastní chyba).
Takže tak.
- David Grudl
- Nette Core | 8249
arron napsal(a):
Až na vyjímky totiž komentář do kódu nepatří!
Proč by ne. Kód říká, co se děje, komentář může doplnit, proč se to děje, není-li to z kódu zřejmé. Což zejména v low-level rutinách fakt být nemusí.
- arron
- Člen | 464
David Grudl wrote:
Proč by ne. Kód říká, co se děje, komentář může doplnit, proč se to děje, není-li to z kódu zřejmé. Což zejména v low-level rutinách fakt být nemusí.
Je to celkem jednoduché:-) Jak píšeš, kód sám o sobě říká co se děje. Pokud je o tom potřeba napsat ještě komentář, pak to kód neříká dost jasně, je špatný a je potřeba ho přepsat tak, aby ho nebylo potřeba doplňovat komentářem. No a pak existují vyjímky, kdy je v kódu nějaká zvláštní konstrukce, která by, hezky přepsaná, byla (například) o 1000% pomalejší, a to je přesně to místo (o kterém Ty zřejmě mluvíš), které spadá pod vyjímky a komentář je zcela na místě.
Ale obecně, proč by komentář měl popisovat to, co popisuje kód, že? A to je bohužel to, co komentáře v kódu většinou dělají a zpravidla je to proto, že ten kód je špatný a potřebuje další vysvětlení (špatně nazvané funkce, špatně nazvané parametry, kód, který patří do své vlastní metody apod.).
Editoval arron (9. 9. 2011 8:57)