- David Grudl
- Nette Core | 8229
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():
nebo příklad dokumentace hodnot proměnných:
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:
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ě:
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í:
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 Grudl
- Nette Core | 8229
Přidám variantu s dump(), ať to můžeme vizuálně posoudit
alternativně:
- paranoiq
- Člen | 392
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()
- Kamil Valenta
- Člen | 820
Dump() mně připadá dost jednoznačný. Pokud je výsledkem řetězec, tak v komentáři v uvozovkách, protože
- Jakub Bouček
- Člen | 54
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
- Nette Core | 8229
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.
- Jakub Bouček
- Člen | 54
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):
Naopak dump()
, echo
i varianta bez nich toto
ustojí:
Editoval Jakub Bouček (14. 7. 2020 15:06)
- David Grudl
- Nette Core | 8229
btw místo nestandardního dump() by mohlo být var_export()
(a místo echo by mohlo být yield)
- Kamil Valenta
- Člen | 820
Ještě se někdy v komentáři používá šipka, což zvýrazní, že jde o výsledek vyhodnocení:
- David Grudl
- Nette Core | 8229
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:
zkouška šipečky (myslím, že není nutná)