Écrire des commentaires pour un petit code avec un fond assez grand
Je devais donc écrire un certain code relatif au scission des courbes de Bezier en parties. J'ai lu plusieurs références et particulièrement référé ceci plutôt détaillé .
Le résultat final du code est toutefois d'environ 20-30 loc. Mais sans avoir ce genre de fond, il serait vraiment difficile pour quelqu'un de comprendre ce que fait le code.
L'expliquer en détail vous obligerait à écrire trop de commentaires que l'explication de la fonction.
Mettre un lien vers ce document dans les commentaires ne semblait pas une très bonne idée (les liens pourraient briser à l'avenir)
Q. Devrais-je plutôt générer cela comme un doc, gardez-le localement avec les documents du projet et y donner une référence dans les commentaires?
Q. Tout autre sens plus agréable en général de donner des commentaires sur une zone de travail plutôt complexe/large associée à une fonctionnalité particulière.
P.s. Je ne veux pas que certains corps lisent ce code plus tard pour me maudir pour ce qu'il est, alors, vous voyez: P
Avoir une grande section de commentaire expliquant "Whays" et "comment" des détails d'un algorithme compliqué est une bonne idée. Et il est préférable d'avoir près du code, de sorte que le développeur n'a pas besoin de changer de contexte pour en lire (même pire - basculer entre algorithme et document).
N'oubliez pas d'inclure une sorte de TL; DR sur le long commentaire, pour ceux qui ont besoin d'obtenir juste l'idée/le contour, sans les détails de la mise en œuvre.
P.s. Je portais un projet avec de tels blocs de commentaire il y a quelques mois - ils étaient très utiles.
Le code est lu bien plus souvent que l'écriture, des commentaires si soigneusement écrits valent leur poids en or.
Distiller les détails pertinents de l'article que vous avez référencé lors de la rédaction du code. Inclure une URL, même si elle peut être brisée à l'avenir; Il y a toujours les archives Internet. Et surtout, faites des références spécifiques aux résultats théoriques que vous avez utilisés, tels que l'algorithme de De Casteljau.
C'est bien que le code soit opaque à une personne inconnue avec le domaine - dans ce cas, des splines et des analyses numériques, tant que le lecteur peut trouver des références détaillées pour l'apprentissage comment pour comprendre le code.
Personnellement, je l'aime s'il y a un commentaire avec suffisamment d'informations pour comprendre le code. Si vous le stockez un endroit d'autre, il y a toujours une chance que cela se perdra jusqu'au moment où quelqu'un essaie de comprendre le code. Néanmoins, mettez un lien là-bas (cela pourrait fonctionner, tout cela peut-être dans les archives Web), s'il y a des papiers, mettez le titre/les auteurs là-bas afin que cela puisse être trouvé.
Mais toujours, Pour quelqu'un qui connaît le domaine, il devrait suffire de lire le commentaire pour comprendre ce qui se passe.
Je ne sais pas ce que vous avez fait exactement et jamais entendu parler de de Casteljau avant, mais peut-être que quelque chose comme ça serait bon:
Splitting the curves into parts because [thats more awesome|i like it|faster›...] using de Casteljau's algorithm.
The following differs from the usual de Casteljau's algorithm:
a. all control points are cats
b. we calculate using roman numerals
Maybe a reason why this differs.
A detailed description is at http://pomax.github.io/bezierinfo/#decasteljau
Also the paper "Towards the use of cats as curve points" by "Meow et al." is of great use (link to paper maybe)
If you want, more detailed description
Cela devrait donner suffisamment d'informations à comprendre le code ou (si on ne connaît pas la théorie derrière elle) trouver des sources d'explication.
Les seuls inconvénients des commentaires plus longs sont la taille du fichier et la nécessité pour les personnes de faire défiler le commentaire. Les deux ne sont pas vraiment un problème (la définition d'aujourd'hui que ce n'est vraiment important pour les systèmes embarqués, etc. et que les commentaires ne sont pas dans les fichiers binaires, et les personnes se plaignent de la nécessité de faire défiler sur un commentaire de 20 lignes devraient obtenir une IDE)
Pensez à cela: Si quelqu'un doit changer de parties de ce code dans quelques années, ce qui coûterait à la société l'employant plus:
- Il a besoin d'ignorer un grand commentaire lors de la modification du code qu'il comprend
- Il doit rechercher des informations sur la manière dont ce code fonctionne ou même la réécrit, car le fichier le décrivant dans le dossier Docs s'est perdu et que les liens sont morts.
Remarque: un argument pour la raison pour laquelle la documentation doit-elle vivre dans le code est effectuée dans la section au bas de cette réponse.
Je vous encourage à inclure les détails de l'algorithme comme un commentaire, etc.
Pourquoi cet algorithme?
Avant d'expliquer l'algorithme lui-même, vous devez d'abord expliquer pourquoi cet algorithme a été choisi, plutôt qu'une alternative.
L'explication peut être aussi simple que "nous utiliserons des courbes de Bezier, aucune autre alternative n'a été explorée car elles ont été assez bien utilisées". Cependant, si vous avez testé des alternatives, veuillez expliquer pourquoi ils ont été rejetés.
L'idée ici est qu'un responsable de maintenance à venir peut-être à explorer à nouveau (à la recherche d'une meilleure performance ou d'une meilleure précision, par exemple), et si vous avez déjà fait le travail avec algorithme X et Y, et les raisons à laquelle ils ont été rejetés sont toujours applicables, puis a déclaré que Mainteneur peut décider de commencer à vérifier un autre algorithme plutôt que de répéter vos expériences.
Quel algorithme?
Pourquoi cela pourrait sembler idiot, voir comme vous l'avez dit "courbes de Bezier", gardez à l'esprit que parfois, il existe de légères variations d'algorithmes/structures de données/... (B-Tree, B * -TREE, B * -TREE, par exemple). Par conséquent, spécifier avec autant de précision que possible que l'algorithme a été sélectionné et quelle source elle a été tirée de (de préférence une en ligne disponible ...) peut aider les attentes des lecteurs avec la réalité.
De plus, s'il s'agit d'une variante par rapport à la version générale du livre textuel, assurez-vous qu'il est clairement étiqueté comme tel, de peur que les lecteurs se demandent pourquoi il semble s'écarter.
Comment fonctionne cet algorithme?
Cela dépend vraiment de l'équipe avec laquelle vous travaillez. Si les courbes de Bézier sont le pain et le beurre de l'équipe, une simple doublure peut être suffisante; Toutefois, si le code peut retrouver être lu/maintenu par des personnes pour lesquelles cela ressemble à une figure de surf, décrivant l'algorithme sonne le mieux.
Deuxièmement, un autre avantage de décrire l'algorithme dans les commentaires est qu'il le rend facile Split la description, un style de programmation alphabétisé. C'est-à-dire que vous commencez par commencer par un aperçu général de l'algorithme qui identifie uniquement les sections, puis pour chaque section, vous aurez un bloc de commentaire et immédiatement sous le code associé. Il est plus facile de vérifier que le code est adéquat avec les commentaires.
Enfin, un dernier avantage de décrire l'algorithme dans les commentaires est qu'il permet d'annoter l'algorithme lui-même. Vous pouvez prendre des coupes courtes (une seule manche d'approximation plutôt que deux est suffisante pour répondre à vos besoins de précision, ou au contraire, expliquez pourquoi une étape donnée est nécessaire (et quelles sont les conséquences de la suppression de la suppression); Vous pouvez même Correction L'algorithme (si vous avez indiqué une version imprimée, par exemple, il pourrait y avoir une errata ...).
Où?
Comme il s'agit d'un détail de mise en œuvre, il ne faut pas entrer dans la voie de l'appelant. Les détails de la mise en œuvre doivent être documentés dans la fonction (non extérieure) et en fonction de votre générateur de documentation, en utilisant des commentaires "purs" car ils n'ont pas besoin d'apparaître dans la documentation.
pourquoi document dans le code?
Je dirai que la documentation du code devrait vivre aussi près que possible du code. La raison est simple:
- le système de suivi des bogues pourrait changer et même si l'outil d'importation fonctionne, les ID peuvent changer.
- le système de contrôle source pourrait changer
- le référentiel pourrait être réorganisé, divisé en plusieurs, etc ...
- ...
Chaque fois qu'un tel événement se produise, il existe un risque que les liens entre les frontières (nouvelles) sont coupées.
Le code est la seule constante!
En effet:
- sans le code, vous n'avez pas besoin de la documentation
- avec le code, vous obtenez les commentaires et donc la documentation dans
Ainsi, la documentation est donc plus susceptible d'être disponible si elle est incluse dans le code.
Il existe évidemment une limite, par exemple, des fichiers texte ne peuvent pas contenir d'images. Les graphiques/diagrammes sont donc difficiles à inclure dans des commentaires (l'art ASCII ne doit pas être sous-estimé, et oui, je suis sérieux). Toujours le texte va un long chemin, donc au moins, vous pouvez fournir une bonne explication en place, puis rien ne vous empêche de fournir également une explication plus approfondie ailleurs et de le lier.
Il semble que toutes les autres réponses soient "Mettez-le dans les commentaires!"
Je vais aller contre le grain et recommande de le garder dans un document séparé aux côtés du code, pour cette raison: il semble que votre code fait quelque chose qui nécessite des calculs compliqués de comprendre. Les mathématiques peuvent être suffisamment difficiles à comprendre dans les meilleurs cas; Cela peut être encore plus difficile à comprendre sans la notation standard appropriée et que les commentaires du code ne sont pas un endroit très facile pour mettre la notation mathématique fantaisie. L'ASCII-ART ne peut vous obtenir que jusqu'à présent.
Au lieu de cela, je voudrais stiptionnez brièvement l'algorithme dans les commentaires du code et voir le document que vous créez dans un outil approprié pouvant afficher le calcul de la fantaisie pour plus de détails. Assurez-vous que ce document est placé dans le même référentiel que le code et stockez-le dans un emplacement peu susceptible d'être omis de tout mouvement futur du code d'un référentiel à un autre ou d'un système de contrôle de version à une autre. Ces choses se passent!
Lorsque je travaille, chaque document officiel associé à un projet obtient un numéro de pièce pouvant être utilisé pour récupérer le document ultérieurement. Si vous avez des processus similaires dans lesquels cette application est en cours d'élaboration, envisagez d'obtenir un numéro attribué au document et de référencer ce numéro dans les commentaires du code afin qu'il existe toujours un moyen de suivre ce document même s'il est perdu.