Opakování dokumentačních komentářů

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 11:54:06

ikona 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 12:55:46

kukulich:

Doxygen podporuje @copydoc MyClass::myfunction().
16.4.2010 16:31:52

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 10:38:48

ikona Jakub Vrána OpenID:

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 11:47:17

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 ...
30.4.2010 13:01:22

ikona Jakub Vrána OpenID:

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.
30.4.2010 13:10:46

ikona Jakub Vrána OpenID:

Neplatí to pro konstruktory (nepřevzaté z interface). Ty můžou parametry měnit beztrestně.
(reakce na) 30.4.2010 13:57:42

Diskuse je zrušena z důvodu spamu.

avatar © 2005-2025 Jakub Vrána. Publikované texty můžete přetiskovat pouze se svolením autora. Ukázky kódu smíte používat s uvedením autora a URL tohoto webu bez dalších omezení Creative Commons. Můžeme si tykat. Skripty předpokládají nastavení: magic_quotes_gpc=Off, magic_quotes_runtime=Off, error_reporting=E_ALL & ~E_NOTICE a očekávají předchozí zavolání mysql_set_charset. Skripty by měly být funkční v PHP >= 4.3 a PHP >= 5.0.