Comment rendre une grande base de code plus facile à comprendre

Supposons que je développe un projet relativement important. J'ai déjà documenté toutes mes classes et fonctions avec Doxygen, cependant, j'ai eu l'idée de mettre une "note du programmeur" sur chaque fichier de code source.

L'idée derrière ceci est d'expliquer en termes simples comment une classe spécifique fonctionne (et pas seulement pourquoi, comme le font la plupart des commentaires). En d'autres termes, donner aux autres programmeurs une autre vision du fonctionnement d'une classe.

Par exemple:

/*
 * PROGRAMMER'S NOTES:
 *
 * As stated in the documentation, the GamepadManager class 
 * reads joystick joystick input using SDL and 'parses' SDL events to
 * Qt signals.
 *
 * Most of the code here is about goofing around the joystick mappings.
 * We want to avoid having different joystick behaviours between
 * operating systems to have a more integrated user experience, since
 * we don't want team members to have a bad surprise while
 * driving their robots with different laptops.
 *
 * Unfortunately, we cannot use SDL's GamepadAPI because the robots
 * are interested in getting the button/axes numbers, not the "A" or
 * "X" button.
 *
 * To get around this issue, we created a INI file for the most common 
 * controllers that maps each joystick button/axis to the "standard" 
 * buttons and axes used by most teams. 
 *
 * We choose to use INI files because we can safely use QSettings
 * to read its values and we don't have to worry about having to use
 * third-party tools to read other formats.
 */

Serait-ce un bon moyen de rendre un grand projet plus facile à comprendre pour les nouveaux programmeurs / contributeurs? Outre le maintien d'un style de codage cohérent et d'une organisation de répertoires «standard», existe-t-il des «normes» ou des recommandations pour ces cas?

C'est génial. Je souhaite que plus de développeurs de logiciels prennent le temps et les efforts nécessaires pour le faire. Il:

• Exprime en anglais clair ce que la classe fait (c'est-à-dire sa responsabilité),
• Fournit des informations supplémentaires utiles sur le code sans répéter textuellement ce que le code dit déjà,
• Décrit certaines des décisions de conception et les raisons pour lesquelles elles ont été prises.
• Met en évidence certains des pièges qui pourraient arriver à la prochaine personne lisant votre code.

Hélas, beaucoup de programmeurs tombent dans le camp de "si le code est écrit correctement, il ne devrait pas être nécessaire de le documenter". Pas vrai. Il existe de nombreuses relations implicites entre les classes de code, les méthodes, les modules et d'autres artefacts qui ne sont pas évidentes à la lecture du code lui-même.

Un codeur expérimenté peut concevoir avec soin une conception ayant une architecture claire, facilement compréhensible et évidente sans documentation. Mais combien de programmes de ce genre avez-vous réellement vus?

La clé pour travailler avec une base de code volumineuse n’est pas obligée de lire la totalité de la base de code pour apporter une modification. Pour permettre au programmeur de trouver rapidement le code qu'il recherche, le code doit être organisé et l'organisation apparente. C'est-à-dire que chaque unité logique dans le code, de l'exécutable à la classe, en passant par la bibliothèque, l'espace de noms, doit avoir une responsabilité clairement apparente. Je voudrais donc non seulement documenter les fichiers source, mais aussi les répertoires dans lesquels ils se trouvent.

Les notes de votre programmeur donnent également un aperçu des décisions de conception. Bien que cela puisse être une information précieuse, je la séparerais de la déclaration de responsabilité (pour permettre au lecteur de choisir s’il souhaite lire la question de la responsabilité de la classe ou de sa logique de conception), et de la déplacer aussi près que possible de la source décrite. dans la mesure du possible, pour maximiser les chances de mise à jour de la documentation lorsque le code l’est (la documentation n’est utile que si nous pouvons nous fier à son exactitude - une documentation obsolète peut être pire que rien!).

Cela dit, la documentation doit rester sèche, c'est-à-dire ne pas répéter les informations qui auraient pu être exprimées en code ou déjà décrites ailleurs (des expressions telles que "comme l'indique la documentation" sont un signe d'avertissement). En particulier, les futurs responsables seront simplement compétents dans le langage de programmation du projet, car ils le sont en anglais; Paraphraser l'implémentation dans les commentaires (ce que je vois trop souvent quand les gens sont fiers de leur documentation) n'a aucun avantage et risque de diverger de l'implémentation, en particulier si la documentation n'est pas proche du code qu'elle décrit.

Enfin, la structure de la documentation doit être normalisée dans tout le projet pour que tout le monde puisse la trouver (c'est un fouillis royal de documents de Peter dans le suivi des bogues, de Sue dans le wiki, d'Alan dans le readme et de John dans le code source ...). .

Je ne suis pas d’accord pour dire que c’est une très bonne approche, principalement en raison de

1. Lorsque vous refactorisez votre projet, déplacez des méthodes, la documentation se rompt.

2. Si la documentation n'est pas correctement mise à jour, la confusion sera plus grande que la compréhension du code.

Si vous avez des tests unitaires pour chaque méthode / tests d'intégration pour chaque module, ce serait une auto-documentation plus facile à gérer et à comprendre, par rapport aux commentaires de code.

Oui, avoir une structure de répertoires appropriée va certainement aider.

Je suis personnellement fan d'un document de conception de haut niveau - de préférence écrit AVANT n'importe quel code - qui donne une vue d'ensemble de la conception et une liste de classes et de ressources. Une conception descendante simplifie énormément les choses - le vôtre pourrait être "moteur de jeu -> matériel -> contrôleurs -> joystick"; ainsi, un nouveau programmeur a déclaré "le bouton" Fixer le bouton "a" sur le "contrôleur xyz" permettrait au moins de savoir par où commencer.

Trop de langues modernes ont tendance à diviser le code en des centaines de petits fichiers. Il peut donc être difficile de trouver le bon fichier, même pour un projet modéré.

Si la base de code est volumineuse, j'essaie de fournir un document de conception qui présente les éléments clés de sa conception et de sa mise en œuvre . L'intention ici n'est pas de détailler les classes utilisées, mais de fournir une clé pour le code et la pensée qui a été prise en compte dans la conception. Il donne un contexte global au système, à ses composants et à ses applications.

Les éléments à inclure dans le document de conception sont:

• Architecture d'application
• Structure de code logique
• Flux de données
• Principaux modèles utilisés et motivation de leur utilisation
• Structure du code source
• Comment le construire (cela donne un aperçu des dépendances implicites et de la structure source du code physique)

Suite à cela, la documentation pour les classes, ainsi que les fonctions / méthodes doivent être complétées le cas échéant . En particulier l'API publique; les éléments suivants doivent être clairement définis dans chaque cas;

• Les conditions
• Effets
• Invariants
• Conditions d'exception (lancers)

La règle la plus importante que j'ai trouvée pour aider les nouveaux développeurs à comprendre une base de code est qu'un accord parfait coûte cher.

Si les nouveaux développeurs doivent parfaitement comprendre le système sur lequel ils travaillent, cela empêche toute possibilité d'apprentissage sur le tas. Je pense que les notes du programmeur sont un excellent début, mais j'irais plus loin. Essayez d'écrire du code qui, s'il était abordé de nouveau, permettrait au développeur de comprendre ce qu'il fait à la volée, plutôt que de le demander à apprendre avant de le faire. De petites choses comme des assertions pour des cas que vous savez ne peuvent jamais se produire, ainsi que des commentaires expliquant pourquoi l'assertion est valide, vont très loin. Il en va de même pour l'écriture de code qui échoue gracieusement plutôt que de commettre une erreur de segmentation si vous faites quelque chose de mal.

J'ai vu de grandes classes avec de la documentation et après avoir lu la documentation, je n'ai pas la moindre idée de ce que cette classe est censée être bonne et pourquoi quelqu'un l'utiliserait! Et en même temps, j'avais besoin de certaines fonctionnalités et j'étais absolument sûr qu'il devait y avoir une classe pour la gérer, et je ne la trouvais nulle part - car aucune documentation ne m'emmenait de ce dont j'avais besoin à la classe. je le fais.

La première chose que je voudrais dans la documentation, ce sont juste quelques phrases de ce que fait une classe et de la raison pour laquelle je voudrais l'utiliser. Les commentaires de la question initiale se portent plutôt bien à cet égard. Après avoir lu ces commentaires, si j’avais un joystick qui ne fonctionnait pas bien car je ne pouvais pas interpréter les valeurs qu’il fournit, je saurais quel code vérifier.

Semblable à ce que @meriton a dit, divisez le code en composants distincts. Mieux encore, divisez la base de code en packages distincts (JAR, gemmes, œufs, etc.) pour que la distinction entre les composants soit encore plus claire. S'il y a un bogue, un développeur doit seulement trouver le paquet contenant le bogue et le corriger (espérons-le) uniquement. Sans oublier qu'il est plus facile de faire des tests unitaires et de tirer parti de la gestion des dépendances.

Une autre solution: réduire la base de code. Moins il y a de code, plus il est facile à comprendre. Refactoriser le code inutilisé ou dupliqué. Utiliser des techniques de programmation déclaratives . Cela demande des efforts, bien sûr, et souvent, cela n’est ni possible ni pratique. Mais c'est un objectif louable. Comme l'a écrit Jeff Atwood: Le meilleur code est aucun code

Pour les systèmes complexes, il peut être intéressant de ne pas documenter chaque fichier, mais également leurs interactions et leur hiérarchie, ainsi que la structure et les raisons du programme.

Par exemple, un moteur de jeu est généralement assez complexe et il est difficile de décider ce qui appelle quoi après cent couches d'abstraction. Il peut être intéressant de créer un fichier tel que "Architecture.txt" pour expliquer comment et pourquoi le code est structuré de la sorte, et pourquoi il existe une couche d'abstraction inutile.

Cela peut être en partie dû au fait qu’il est difficile pour un seul programmeur de l’écrire, car chaque individu ne comprend que sa partie du projet.

Parfois, vous pouvez obtenir ces informations à partir des notes du chef de projet, mais c’est tout ce que vous obtiendrez, car elles réécriront rarement leurs notes dans ce format.