Comment documenter des structures de code nécessairement complexes?

Si j'ai un morceau de code mathématiquement ou structurellement assez complexe et irréductible, comment pourrais-je documenter ce morceau de code? En particulier, comment puis-je m'assurer que quelqu'un qui ne possède pas les compétences mathématiques ou architecturales que je fais peut le comprendre à partir de la documentation? Dois-je également documenter tous les calculs? Lien vers un tutoriel? Est-ce que certains liens visuels d'aide dans le cas de structures complexes?

Cela dépend vraiment de la complexité du code et des mathématiques. Le code lui-même devrait - comme toujours - être le plus documenté possible. Nommez les variables correctement, implémentez des méthodes logiques et concises (plutôt que des méga-fonctions), ajoutez de la documentation en ligne le cas échéant (c'est-à-dire lorsqu'il n'est pas évident de savoir ce que le code fait réellement).

Si vous utilisez un algorithme non évident, ajoutez un lien vers une référence à la source. C'est une pratique raisonnable car elle permet au développeur de découvrir très rapidement ce que vous faites. Comme je l'ai dit, cela est utile s'il s'agit d'un algorithme non évident mais complexe. Cela devrait prouver que (a) vous faites quelque chose qui a du sens, et (b) quelqu'un a démontré que cela fonctionne.

Un bon exemple est un travail que j'ai fait sur la correspondance de texte flou. J'ai fait des recherches approfondies sur les algorithmes et mis en œuvre ce que l'on appelle «l'algorithme de Smith-Waterman» (qui est en fait utilisé pour les séquences d'ADN, mais s'applique à la «correspondance» en général). Donc, au lieu de simplement implémenter l'algorithme, j'ai trouvé des références en ligne et j'ai inclus un lien ou deux. Comme ci-dessus, cela démontre que (a) mon algorithme correspond à l'algorithme publié, et (b) l'algorithme a été révisé et a montré son fonctionnement.

Cependant, cela n'explique pas nécessairement comment le code fonctionne et ce que les différentes classes sont censées faire. Lorsque vous allez écrire de la «vraie» documentation - un guide du développeur du système - vous devez expliquer ce que vous avez fait et fournir suffisamment d'informations pour une assistance future. À mon avis, ce document devrait être lisible par une personne techniquement agnostique; il n'a pas besoin d'être «abruti» mais il doit exclure le jargon et ne pas s'appuyer sur des connaissances supposées.

Les commentaires entourant la source sont la première chose à faire. Cela garantit qu'il existe un lien direct vers la documentation juste à côté du code. Si la documentation est très compliquée, envisagez de publier uniquement un résumé dans les commentaires, puis un lien vers un document externe contenant une description plus complète de l'architecture / algorithme complexe. Si ce n'est pas trop compliqué, pensez à inclure toute la documentation au même endroit. Cela maximisera la probabilité que votre code / documentation reste synchronisé et soit lu ensemble.

Documentez le code dans la mesure où votre équipe / entreprise en a besoin. Si un jr. dev va être nécessaire pour maintenir le code, vous devrez peut-être entrer dans les détails sur certaines des mathématiques. Il s'agit d'une décision de gestion et ils doivent vous donner le temps nécessaire.

Je ne pense pas que vous deviez tellement documenter le code que vous pensez être remplacé par un développeur moins important. Si cela vous inquiète, vous devez avoir le temps de documenter.

Vous ne devriez pas avoir à les rechercher sur le Web.