Jak dokumentovat návratové hodnoty?

David Grudl

Docela si lámu hlavu s tím, jak v příkladech dokumentovat hodnoty, které vrací funkce nebo obsahují proměnné.

Příklad dokumentace návratových hodnot ucwords():

echo ucwords('ahoj');       // Ahoj
echo ucwords('ahoj svete'); // Ahoj Svete
echo ucwords('AHOJ');       // AHOJ

nebo příklad dokumentace hodnot proměnných:

$rm = new ReflectionMethod('PDO::query');
echo $rm->class; // PDO
echo $rm->name;  // query

Echo je pěkné v tom, že je stručné a jasně vystihuje, že popisujeme návratovou hodnotu či hodnotu proměnné, ale hodí se pouze pro řetězce.

Z toho není jasné, jestli to vrací řetězec null nebo fakt null, atd:

echo $obj->foo;  // null

Vůbec se nehodí pro objekty a pole, echo $arr vypadá jako chyba.

Hledám proto jiný způsob dokumentování. Jednou z možností je echo vynechat úplně:

ucwords('ahoj');       // 'Ahoj'
ucwords('ahoj svete'); // 'Ahoj Svete'

$rm = new ReflectionMethod('PDO::query');
$rm->class;    // 'PDO'
$rm->name;     // 'query'

$obj->foo;     // false
$obj->foo();   // true

$arr;          // [1, 2, 3]

Ono to není vlastně špatné… dokonce po jazykové stránce velmi přesné. Ale nejsem si tím úplně jiný. Je fakt patrné, že řeším výstup? Bude to jasné i u jednotlivé proměnné, jako $arr?

Teoreticky je možnost naznačit přiřazení:

$res = ucwords('ahoj');       // 'Ahoj'
$res = ucwords('ahoj svete'); // 'Ahoj Svete'

$rm = new ReflectionMethod('PDO::query');
$res = $rm->class;    // 'PDO'
$res = $rm->name;     // 'query'

$res = $obj->foo;     // false
$res = $obj->foo();   // true

Tady musím říct, že mám tendenci dohledávat, jestli se pak proměnná $res někde nepoužila.

Napadá vás nějaký lepší způsob?

David Matějka

co takhle

ucwords('ahoj svete') === 'Ahoj Svete';

$obj->foo === false;

nebo namisto echo tam mit var_dump ?

David Grudl

:-))

$obj->foo === false; // false

David Grudl

Přidám variantu s dump(), ať to můžeme vizuálně posoudit

dump(ucwords('ahoj'));       // 'Ahoj'
dump(ucwords('ahoj svete')); // 'Ahoj Svete'

$rm = new ReflectionMethod('PDO::query');
dump($rm->class);    // 'PDO'
dump($rm->name);     // 'query'

dump($obj->foo);     // false
dump($obj->foo());   // true

dump($arr);          // [1, 2, 3]

alternativně:

dump( ucwords('ahoj') );       // 'Ahoj'
dump( ucwords('ahoj svete') ); // 'Ahoj Svete'

$rm = new ReflectionMethod('PDO::query');
dump( $rm->class );    // 'PDO'
dump( $rm->name );     // 'query'

dump( $obj->foo );     // false
dump( $obj->foo() );   // true

dump( $arr );          // [1, 2, 3]

paranoiq

ten příklad o osamělým $arr vypadá divně, ale v reálném příkladu se do $arr ta hodnota musela nějak dostat, tak bych jí popisoval na tom místě, kde je přiřazena

problém asi je, pokud by se tam dostala referencí z parametru metody/funkce. to by asi byl jediný případ, kdy by skutečně musela být samotná proměnná zdokumentovaná takhle mimo. ale to se moc často nepoužívá

jinak mi to přijde nejpředhlednější bez echo a bez dump()

David Grudl

Varianta s rovnítky:

ucwords('ahoj')       === 'Ahoj'
ucwords('ahoj svete') === 'Ahoj Svete'

$rm = new ReflectionMethod('PDO::query');
$rm->class  === 'PDO'
$rm->name   === 'query'

$obj->foo   === false
$obj->foo() === true

$arr        === [1, 2, 3]

Kamil Valenta

Dump() mně připadá dost jednoznačný. Pokud je výsledkem řetězec, tak v komentáři v uvozovkách, protože

dump($foo); // null
dump($bar); // 'null'

ic

Intuitivně mám vždy největší problém s možnostmi… seznam položek jedna nebo druhá, nebo třetí, nebo… .

Protože se často značí snadno zaměnitelné s návratovým typem pole hodnot.

Jakub Bouček

Vizuálně se mi líbí to echo, ale je fakt, že pak není výpis jednoznačný.

dump je asi nejlepší řešení, který vytváří jednoznačný výsledek, ale zase mě tam hodně ruší ty jeho závorky, které echo nepotřebuje.

Naopak prosím === ne, to je zcela matoucí a intuitivně mě to nevede k tomu, že by to měla být předpokládaná návratová hodnota.

Editoval Jakub Bouček (14. 7. 2020 14:47)

David Grudl

Zkusmo jsem dal do docky to === a není to úplně jednoznačné…

https://dev.nette.org/cs/strings vs https://doc.nette.org/…tils/strings

Problematické to je, když je výstupem objekt.

Šaman

Ten komentář je běžně používaný všude. Trojrovnítko mi přijde matoucí, vypadá to jako kus kódu, na první pohled ale není jasné co to říká.

Strings::lower('Dobrý den') === 'ahoj' // false

Jakub Bouček

David Grudl napsal(a):

Zkusmo jsem dal do docky to === a není to úplně jednoznačné…
https://doc.nette.org/…tils/strings vs https://doc.nette.org/…tils/strings

Porovnal jsem to a z mých dosavadních zvyklostí s dokumentací i pocitově je klasický komentář pěkně výrazný tím, že je od kódu oddělen barvou, zatímco porovnání vypadá jako aktivní kus kódu, jehož význam ale není z použití zřejmý. Navíc by se tím znemožnilo naznačení návratové hodnoty tam, kde se rovnou používá přiřazení (v nějaké delší ukázce kódu):

$foo = Strings::substring('Nette Framework', -4) === 'work'

Naopak dump(), echo i varianta bez nich toto ustojí:

dump( $foo = Strings::substring('Nette Framework', -4) ) // 'work'

dump($foo = Strings::substring('Nette Framework', -4)) // 'work'

echo $foo = Strings::substring('Nette Framework', -4) // 'work'

$foo = Strings::substring('Nette Framework', -4) // 'work'

Editoval Jakub Bouček (14. 7. 2020 15:06)

David Grudl

btw místo nestandardního dump() by mohlo být var_export()

(a místo echo by mohlo být yield)

Kamil Valenta

Ještě se někdy v komentáři používá šipka, což zvýrazní, že jde o výsledek vyhodnocení:

var_export($foo = Strings::substring('Nette Framework', -4)) // => 'work'

David Grudl

Používání funkcí se mi asi nelíbí… dump() je proprietální, var_export() není tolik známá, všechny vytváří až příliš mnoho šumu v ukázkách kódu.

Trojrovnítko může být matoucí, to by vyžadovalo asi větší průzkům.

Takže nejspíš zůstanu u komentářů, ale odstraním echo.

Možná by pomohlo vynechat středníky a psát záměrně nevalidní kód:

ucwords('ahoj')       // 'Ahoj'
ucwords('ahoj svete') // 'Ahoj Svete'

$rm = new ReflectionMethod('PDO::query');
$rm->class    // 'PDO'
$rm->name     // 'query'

$obj->foo     // false
$obj->foo()   // true

$arr          // [1, 2, 3]

zkouška šipečky (myslím, že není nutná)

ucwords('ahoj');       // => 'Ahoj'
ucwords('ahoj svete'); // => 'Ahoj Svete'

$rm = new ReflectionMethod('PDO::query');
$rm->class;    // => 'PDO'
$rm->name;     // => 'query'

$obj->foo;     // => false
$obj->foo();   // => true

$arr;          // => [1, 2, 3]

Felix

Mne se nejvic libi varianta bez echo/dump a se strednikem/komentarem.