Zamyšlení nad komentováním kodu

Lweek

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

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

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

Já bych byl drsnější. Pokud nějaký kód potřebuju vyřadit, tak ho smažu. Máme Git.

22

@lweek: pokud to máš takový blok s jedním odsazením, tak je to čitelnější, ale pokud jsi ve 3–4 zanoření, tedy myslím 3–4 tabulátory, tak bez IDE a barviček ti značku na začátku řádku v klidu přehlídnu :-) aspoň já

Lweek

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

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?

22

a který editor myslíš, mě na phpEd ta paráda nefunguje…

hrach

Ja používám mřížku – pro:

jeden znak
typograficky vyraznějš

proti:

v jiných jazycích není – je toto vůbec argument???

Lweek

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

@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

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

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

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)

David Grudl

Nejsme ve sporu, argumentuješ proti nečemu jinému, než jsem psal.

arron

David Grudl wrote:

Nejsme ve sporu, argumentuješ proti nečemu jinému, než jsem psal.

V tom případě jsem Tě nepochopil :-)

wdolek

IMHO znak „#“ je „one-line shell-style comment“… a jelikoz je PHP blizsi k syntaxi C/C++, z estetickeho hlediska bych vubec mrizku ke komentovani kodu nepouzival. Ale to je zkratka stara kosile, respektive zvyk.