La documentation en POO doit éviter de spécifier si un «getter» effectue un calcul ou non.

Le programme CS de mon école évite toute mention de la programmation orientée objet. Je me suis donc mis à lire moi-même pour la compléter, en particulier la Construction de logiciels orientés objet de Bertrand Meyer.

Meyer insiste à plusieurs reprises sur le fait que les classes doivent cacher autant d'informations que possible sur leur implémentation, ce qui est logique. En particulier, il soutient à plusieurs reprises que les attributs (c'est-à-dire les propriétés statiques, non calculées de classes) et les routines (propriétés de classes qui correspondent à des appels de fonction / procédure) ne devraient pas être distingués l'un de l'autre.

Par exemple, si une classe Persona l'attribut age, il affirme qu'il devrait être impossible de dire, à partir de la notation, si Person.agecorrespond en interne à quelque chose comme return current_year - self.birth_dateou simplement return self.age, où self.agea été défini en tant qu'attribut constant. Cela a du sens pour moi. Cependant, il continue en affirmant ce qui suit:

La documentation client standard d'une classe, appelée forme abrégée, sera conçue de manière à ne pas révéler si une caractéristique donnée est un attribut ou une fonction (dans les cas où elle pourrait l'être).

c'est-à-dire qu'il affirme que même la documentation de la classe devrait éviter de spécifier si un "getter" effectue ou non un calcul.

Ceci, je ne suis pas. La documentation n'est-elle pas le seul endroit où il serait important d'informer les utilisateurs de cette distinction? Si je devais concevoir une base de données contenant des Personobjets, ne serait-il pas important de savoir si l' Person.ageappel est coûteux ou non , afin que je puisse décider de mettre en œuvre ou non une sorte de cache pour celui-ci? Ai-je mal compris ce qu'il dit ou est-il simplement un exemple particulièrement extrême de la philosophie de conception de la programmation orientée objet?

Je ne pense pas que le point de Meyer, c'est que vous ne devriez pas dire à l'utilisateur quand vous avez une opération coûteuse. Si votre fonction doit accéder à la base de données, ou faire une demande à un serveur Web, et passer plusieurs heures en calcul, il faudra que le code suivant le sache.

Mais le codeur utilisant votre classe n'a pas besoin de savoir si vous avez implémenté:

return currentAge;

ou:

return getCurrentYear() - yearBorn;

Les caractéristiques de performance entre ces deux approches sont tellement minimes que cela ne devrait pas avoir d'importance. Le codeur qui utilise votre classe ne devrait vraiment pas se soucier de ce que vous avez. C'est le point de mon yer.

Mais ce n'est pas toujours le cas, par exemple, supposons que vous ayez une méthode de taille sur un conteneur. Cela pourrait être mis en œuvre:

return size;

ou

return end_pointer - start_pointer;

ou ce pourrait être:

count = 0
for(Node * node = firstNode; node; node = node->next)
{
    count++
}
return count

La différence entre les deux premiers ne devrait vraiment pas avoir d'importance. Mais le dernier pourrait avoir de graves conséquences sur les performances. C'est pourquoi le TSL, par exemple, dit que .size()c'est le cas O(1). Il ne documente pas exactement comment la taille est calculée, mais il me donne les caractéristiques de performance.

Donc : documentez les problèmes de performance. Ne documentez pas les détails de la mise en œuvre. Je me fiche de savoir comment std :: sort trie mes données, tant que cela fonctionne correctement et efficacement. Votre classe ne devrait pas non plus documenter comment elle calcule les choses, mais si quelque chose a un profil de performance inattendu, documentez-le.

D'un point de vue académique ou puriste CS, il s'agit bien sûr d'un échec dans la documentation pour décrire quoi que ce soit sur les éléments internes de la mise en œuvre d'une fonctionnalité. En effet, l'utilisateur d'une classe ne devrait idéalement pas émettre d'hypothèses sur son implémentation interne. Si la mise en œuvre change, idéalement, aucun utilisateur ne le remarquera - la fonctionnalité crée une abstraction et les éléments internes doivent rester complètement masqués.

Cependant, la plupart des programmes du monde réel souffrent de la "loi des abstractions qui fuit" de Joel Spolsky , qui dit

"Toutes les abstractions non triviales, dans une certaine mesure, ont des fuites."

Cela signifie qu'il est pratiquement impossible de créer une abstraction complète des entités complexes dans une boîte noire. Et un symptôme typique de ceci est des problèmes de performances. Ainsi, dans le cas de programmes réels, il peut être très important de savoir quels appels coûtent cher ou non, et une bonne documentation devrait inclure cette information (ou indiquer où l'utilisateur d'une classe est autorisé à émettre des hypothèses sur les performances, et où il n'en est pas ainsi. ).

Mon conseil est donc le suivant: incluez les informations sur les appels potentiellement coûteux si vous écrivez des documents pour un programme réel, et excluez-les pour un programme que vous écrivez uniquement à des fins éducatives de votre cours CS, étant donné que toute considération de performance doit être conservée intentionnellement hors de portée.

Vous pouvez écrire si un appel donné est coûteux ou non. Mieux, utilisez une convention de dénomination comme getAgepour un accès rapide loadAgeou fetchAgepour une recherche coûteuse. Vous voulez absolument informer l'utilisateur si la méthode exécute des E / S.

Chaque détail que vous donnez dans la documentation est comme un contrat qui doit être honoré par la classe. Il devrait informer sur le comportement important. Souvent, vous verrez des indications de complexité avec la grande notation O. Mais vous voulez généralement être bref et concis.

Si je devais concevoir une base de données remplie d'objets Person, ne serait-il pas important de savoir si Person.age est un appel coûteux?

Oui.

C'est pourquoi j'utilise parfois des Find()fonctions pour indiquer que l'appel peut durer un certain temps. C'est plus une convention qu'autre chose. Le temps qu'il faut pour une fonction ou à un retour ne fait aucune différence au programme (bien qu'il pourrait à l'utilisateur), bien que parmi les programmeurs il est une attente, si elle est déclarée comme un attribut, le coût de l' appeler devrait être faible.

Dans tous les cas, le code lui-même devrait contenir suffisamment d'informations pour en déduire qu'il s'agit d'une fonction ou d'un attribut. Par conséquent, je ne vois pas vraiment la nécessité de le mentionner dans la documentation.

Il est important de noter que la première édition de ce livre a été écrite en 1988, au début de la programmation orientée objet. Ces personnes travaillaient avec des langages plus purement orientés objet qui sont largement utilisés aujourd'hui. Nos langages OO les plus populaires aujourd'hui - C ++, C # et Java - présentent des différences assez significatives par rapport au fonctionnement des langages anciens, plus purement OO.

Dans un langage tel que C ++ et Java, vous devez faire la distinction entre l'accès à un attribut et un appel de méthode. Il y a un monde de différence entre instance.getter_methodet instance.getter_method(). L'un obtient réellement votre valeur et l'autre pas.

Lorsque vous travaillez avec un langage plus purement OO, de persuasion Smalltalk ou Ruby (ce qui semble être le langage Eiffel utilisé dans ce livre), il devient un conseil parfaitement valide. Ces langages appellent implicitement des méthodes pour vous. Il ne devient plus aucune différence entre instance.attributeet instance.getter_method.

Je ne voudrais pas transpirer ce point ou le prendre trop dogmatiquement. L'intention est bonne - vous ne voulez pas que les utilisateurs de votre classe s'inquiètent de détails d'implémentation non pertinents - mais cela ne correspond pas parfaitement à la syntaxe de nombreuses langues modernes.

En tant qu'utilisateur, vous n'avez pas besoin de savoir comment quelque chose est implémenté.

Si les performances sont un problème, il faut faire quelque chose dans l'implémentation de la classe, pas autour. Par conséquent, l’action correcte consiste à corriger l’implémentation de la classe ou à signaler un bogue au responsable.

Toute documentation orientée programmeur qui ne renseigne pas les programmeurs sur le coût en complexité des routines / méthodes est erronée.

• Nous cherchons à produire des méthodes sans effets secondaires.

• Si l'exécution d'une méthode a une complexité d'exécution et / ou de mémoire autre que O(1), dans les environnements soumis à une mémoire ou à une contrainte de temps, des effets secondaires peuvent être considérés .

• Le principe de la moindre surprise est violé si une méthode effectue quelque chose de complètement inattendu - dans ce cas, monopoliser de la mémoire ou perdre du temps processeur.

Je pense que vous l'avez bien compris, mais je pense aussi que vous avez un bon argument. Si Person.ageest implémenté avec un calcul coûteux, alors je pense que j'aimerais aussi voir cela dans la documentation. Cela peut faire la différence entre l'appeler de manière répétée (s'il s'agit d'une opération peu coûteuse) ou l'appeler une fois et mettre en cache la valeur (si elle est chère). Je ne sais pas avec certitude, mais je pense que dans ce cas, Meyer pourrait convenir qu'un avertissement dans la documentation devrait être inclus.

Une autre façon de gérer cela consiste à introduire un nouvel attribut dont le nom implique un long calcul (tel que Person.ageCalculatedFromDB) et à Person.agerenvoyer ensuite une valeur mise en cache dans la classe, mais cela peut ne pas toujours être approprié et sembler trop compliqué. les choses, à mon avis.

La documentation pour les classes orientées objet implique souvent un compromis entre donner aux responsables de la classe une flexibilité pour changer de conception et permettre aux consommateurs de la classe d'exploiter pleinement son potentiel. Si une classe immuable aura un certain nombre de propriétés qui ont une certaine exacte relation les uns avec les autres (par exemple le Left, RightetWidthles propriétés d’un rectangle à coordonnées entières alignées sur la grille), on peut concevoir que la classe stocke toute combinaison de deux propriétés et calcule la troisième, ou l’utiliser pour stocker les trois. Si rien dans l'interface n'indique clairement quelles propriétés sont stockées, le programmeur de la classe pourra peut-être modifier la conception dans le cas où cela s'avérerait utile pour une raison quelconque. En revanche, si, par exemple, deux des propriétés sont exposées en tant que finalchamps et que la troisième ne l'est pas, les versions futures de la classe devront toujours utiliser les deux mêmes propriétés en tant que "base".

Si les propriétés n'ont pas une relation exacte (par exemple parce qu'elles sont floatou doubleplutôt que int), il peut être nécessaire de documenter quelles propriétés "définissent" la valeur d'une classe. Par exemple, même si Leftplus Widthest supposé être égal Right, les calculs en virgule flottante sont souvent inexacts. Par exemple, supposons que a Rectanglequi utilise le type Floataccepte Leftet Widthque les paramètres du constructeur soient construits avec Leftdonnes comme 1234567fet Widthcomme 1.1f. La meilleure floatreprésentation de la somme est 1234568.125 [pouvant afficher 1234568.13]; le prochain plus petit floatserait 1234568.0. Si la classe stocke réellement LeftetWidth, il peut signaler la valeur de la largeur telle qu’elle a été spécifiée. Si, toutefois, le constructeur calculait en Rightfonction de l'entrée Leftet Width, et plus tard, en Widthfonction de Leftet Right, il indiquerait la largeur comme 1.25fplutôt que comme entrée 1.1f.

Avec les classes mutables, les choses peuvent être encore plus intéressantes, puisqu'un changement à l'une des valeurs interdépendantes impliquera un changement à au moins une autre, mais on ne sait pas toujours laquelle. Dans certains cas, il peut être préférable d'éviter d' avoir des méthodes qui « ensemble » une seule propriété en tant que telle, mais soit avoir des méthodes pour par exemple SetLeftAndWidthou SetLeftAndRight, ou bien préciser ce que les propriétés sont spécifiées et qui changent (par exemple MoveRightEdgeToSetWidth, ChangeWidthToSetLeftEdgeou MoveShapeToSetRightEdge) .

Parfois, il peut être utile d’avoir une classe qui garde en mémoire les valeurs des propriétés spécifiées et celles calculées par d’autres. Par exemple, une classe "moment dans le temps" peut inclure une heure absolue, une heure locale et un décalage de fuseau horaire. Comme avec beaucoup de ces types, étant donné deux informations quelconques, on peut calculer la troisième. Sachant lequelDes informations ont été calculées, cependant, peuvent parfois être importantes. Par exemple, supposons qu’un événement soit enregistré comme s’il s’est produit à "17h00 UTC, fuseau horaire -5, heure locale 12h00", et on découvre plus tard que le fuseau horaire aurait dû être -6. Si l’on sait que l’heure UTC a été enregistrée sur un serveur, l’enregistrement doit être corrigé comme suit: "18 h 00 UTC, fuseau horaire -6, heure locale 12 h 00"; si quelqu'un tape l'heure locale sur une horloge, il devrait s'agir de "17:00 UTC, fuseau horaire -6, heure locale 11:00 am". Sans savoir si l'heure locale ou globale doit être considérée comme "plus crédible", il est toutefois impossible de savoir quelle correction doit être appliquée. Si, toutefois, l'enregistrement garde trace de l'heure spécifiée, des modifications du fuseau horaire peuvent laisser celui-ci seul pendant le changement de l'autre.

Toutes ces règles sur la manière de cacher des informations dans des classes sont parfaitement logiques dans l’hypothèse où il est nécessaire de se protéger contre cette personne parmi les utilisateurs de la classe qui commettra l’erreur de créer une dépendance vis-à-vis de la mise en oeuvre interne.

C'est bien d'intégrer une telle protection, si la classe a un tel public. Mais lorsque l'utilisateur écrit un appel vers une fonction de votre classe, il vous fait confiance avec son compte bancaire au moment de l'exécution.

Voici le genre de chose que je vois beaucoup:

1. Les objets ont un bit "modifié" indiquant s'ils sont, dans un certain sens, obsolètes. C'est assez simple, mais comme ils ont des objets subordonnés, il est donc simple de laisser «modifié» être une fonction qui additionne tous les objets subordonnés. Ensuite, s’il existe plusieurs couches d’objets subordonnés (partageant parfois plusieurs fois le même objet), les simples "Get" de la propriété "modifiée" peuvent finir par prendre une fraction saine du temps d’exécution.

2. Lorsqu'un objet est modifié d'une manière ou d'une autre, il est supposé que les autres objets dispersés dans le logiciel doivent être "notifiés". Cela peut se produire sur plusieurs couches de structure de données, fenêtres, etc. écrites par différents programmeurs et se répétant parfois dans des récursions infinies contre lesquelles il faut se protéger. Même si tous les rédacteurs de ces gestionnaires de notifications veillent raisonnablement à ne pas perdre de temps, toute l’interaction composite peut aboutir à une fraction du temps d’exécution imprévue et douloureusement longue, et l’hypothèse selon laquelle elle est simplement "nécessaire" est prise allègrement.

SO, j'aime voir des classes qui présentent une belle interface abstraite avec le monde extérieur, mais j'aime bien avoir une idée de leur fonctionnement, ne serait-ce que pour comprendre le travail qu'elles me font économiser. Mais au-delà de ça, j'ai tendance à penser que "moins, c'est plus". Les gens sont tellement épris de la structure de données qu'ils croient que plus c'est mieux, et quand je règle les performances, la raison majeure et universelle des problèmes de performance est une adhésion servile aux structures de données gonflées qui sont construites de la même manière que les gens.

Alors allez comprendre.

L'ajout de détails d'implémentation tels que "calculer ou non" ou "informations de performance" rend plus difficile la synchronisation du code et de la documentation .

Exemple:

Si vous avez une méthode "coûteuse en performances", voulez-vous documenter "cher" également à toutes les classes qui l'utilisent? Et si vous changiez l'implémentation pour qu'elle ne soit plus chère? Voulez-vous mettre à jour cette information à tous les consommateurs?

Bien sûr, il est agréable pour un mainteneur de code d’obtenir toutes les informations importantes de la documentation du code, mais je n’aime pas la documentation qui réclame quelque chose qui n’est plus valide (non synchronisée avec le code)

Alors que la réponse acceptée arrive à la conclusion:

Donc: documentez les problèmes de performance.

et le code auto-documenté est considéré comme meilleur que la documentation, il s'ensuit que le nom de la méthode doit indiquer tout résultat de performance inhabituel.

Donc encore Person.agepour return current_year - self.birth_datemais si la méthode utilise une boucle pour calculer l'âge (oui):Person.calculateAge()