Opakování dokumentačních komentářů
Školení, která pořádám 
Pokud rozhraní deklaruje nějaké metody, tak by tyto metody jistě měly mít dokumentační komentáře. A co když pak někdo tyto metody definuje, má dokumentační komentáře psát znovu? Není to zbytečná práce navíc? A když se původní dokumentační komentáře změní, má se měnit i u všech implementací?
K podobné situaci dochází i u abstraktních tříd a dědičnosti obecně, tam už ale metoda může přijímat třeba i jiné parametry, takže se význam metody může snáz posunout.
Já se kloním k tomu, že by měl být všechen kód kromě identifikátorů zapsán pouze jednou, což platí to i pro komentáře. Komentář v implementaci by podle mě dával smysl pouze v případě, když by se definice lišila od deklarovaného chování, k tomu by ale nemělo docházet.
Pak jde jen o to mít dostatečně schopný nástroj pro generování dokumentace a IDE, které dokážou dědit i dokumentační komentáře.
<?php
interface IPlugin {
/** Instalace do zadané cesty
* @param string
* @return bool
*/
function install($path);
/** Odinstalace
* @return bool
*/
function uninstall();
}
class PluginJush implements IPlugin {
// tady už žádný dokumentační komentář nebude
function install($path) {
}
function uninstall() {
}
}
?>
Diskuse
Michal Till:
Příjde mi to celkem jednoznačný. Stejně se programuje oproti interface a ne implementaci, intrface je tak ta hlavní věc.
Docela hezké mi přijde
/**
* @see IPlugin::uninstall()
*/
Alespoň vím, ve kterém rozhraní je metoda deklarována (zvlášť, když jich třída implementuje víc).
kukulich:
Doxygen podporuje @copydoc MyClass::myfunction().
jos:
"K podobné situaci dochází i u abstraktních tříd a dědičnosti obecně, tam už ale metoda může přijímat třeba i jiné parametry, takže se význam metody může snáz posunout."
deklarace metody odlišná od předka generuje E_STRICT, takže nic co by se dalo použít
Neřekl bych. Následující kód nevyvolá žádnou chybu.
<?php
error_reporting(E_ALL | E_STRICT);
class Predek {
function f() {
}
}
class Potomek extends Predek {
function f($x) {
}
}
?>
jos:
aha, asi je to závislý na verzi PHP, s 5.3.1
Strict Standards: Declaration of Potomek::f() should be compatible with that of Predek::f() in ...
Na verzi PHP to nezávisí, ale kontroluje se to už při kompilaci.
Takže máš pravdu, opravdu to vyvolává chybu E_STRICT.
Neplatí to pro konstruktory (nepřevzaté z interface). Ty můžou parametry měnit beztrestně.
Vložit komentář