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() {
    }
}
?>

Jakub Vrána, Dobře míněné rady, 16.4.2010, diskuse: 8 (nové: 0)

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.

16.4.2010 12:54:06 reagovat

Ondřej Brejla:

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).

16.4.2010 13:55:46 reagovat

kukulich:

Doxygen podporuje @copydoc MyClass::myfunction().

16.4.2010 17:31:52 reagovat

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

30.4.2010 11:38:48 reagovat

Jakub Vrána :

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) {
}
}
?>

30.4.2010 12:47:17 reagovat