Quand les exceptions devraient-elles être documentées?

On suppose l'extrait suivant:Quand les exceptions devraient-elles être documentées?

public function foo() 
{ 
    return $this->dependency->bar(); 
}

Si dependency::bar() est connu pour lancer une exception, mais foo() ne devrait pas y faire face. Est-ce que foo() doit avoir une entrée @throws dans son docblock? Ou devrait-il être implicite? La documentation de phpdoc est quelque peu vague à ce sujet.

En supposant que dependency est injecté sur la base d'une interface; devrait le document d'interface que la méthode peut jeter l'exception spécifiée.

Est-ce que l'exception doit être traitée par le code appelant ou est-ce que cela n'a pas d'importance pour la situation?

Sémantique tout le chemin :)

Source

2017-10-10 Timo

Dans d'autres langues (java) est obligatoire de définir explicitement quelles exceptions sont levées (et non traitées) dans le corps de la fonction. Cela peut sembler un peu pénible si vous gérez l'exception bien au-delà de la pile des appels, mais l'ajout d'informations ne peut pas nuire. (Dans ce cas précis, comme vous l'avez dit, foo ne gère pas l'exception, et foo ne sait pas si l'appelant va le gérer, donc, d'après foo, il devrait être noté) – Gerard

Depuis $ this-> dependency -> bar() 'est un détail d'implémentation interne que l'appelant et/ou le responsable de la documentation ne peuvent/ne doivent pas connaître, documenter l'exception est le seul moyen de la rendre attrayante. – deceze

btw si vous utilisez PhpStorm - IDE vous encouragera à avoir de telles exceptions dans l'entrée @throws. –

Vous avez créé la fonction publique (tout le monde peut l'utiliser) qui, dans certains cas, peut jeter exception - donc vous avez certainement d'avoir l'entrée @throws dans votre docblock.
Si une exception se produit à partir de votre dépendance - c'est votre implémentation interne et elle est encapsulée - donc quelqu'un qui utilisera votre fonction n'aura aucune idée de ce que vous attendez de votre fonction.

En cas d'injection d'interface - l'interface doit décrire toutes les exceptions car les exceptions font partie du comportement de la classe et l'interface doit décrire tous les comportements possibles.

Dans le cas où vous avez try-catch bloquer et gérer toutes les exceptions de dépendances - vous devez avoir seulement vos propres exceptions dans l'entrée @throws dans votre docblock.

Source

2017-10-10 11:44:14

Pourriez-vous, par souci de clarté, saisir et renvoyer l'erreur? – Timo

@Timo Oui, vous pouvez le faire et vous devez décrire votre exception dans le bloc '@ throw '. –

Quand les exceptions devraient-elles être documentées?

Répondre

Questions connexes