Comment promouvoir la réutilisation et la documentation du code? [fermé]

En tant que chef d'équipe d'environ 10+ développeurs, je voudrais promouvoir la réutilisation du code. Nous avons écrit beaucoup de code - beaucoup d'entre eux sont répétitifs au cours des dernières années. Le problème est maintenant que beaucoup de ces codes sont simplement des doublons d'un autre code ou une légère variation d'entre eux.

J'ai commencé le mouvement (discussion) sur la façon de transformer le code en composants afin qu'ils puissent être réutilisés pour les futurs projets, mais le problème est que j'ai peur que les nouveaux développeurs ou d'autres développeurs qui ignorent les composants avancent et écrire leur propre truc.

Est-il possible de rappeler aux développeurs de réutiliser les composants / d'améliorer la documentation / de contribuer au composant sous-jacent au lieu de dupliquer le code existant et de le peaufiner ou simplement d'écrire le leur?

Comment rendre les composants facilement détectables, facilement utilisables pour que tout le monde les utilise?

Je pense que chaque développeur connaît les avantages des composants réutilisables et veut les utiliser, c'est juste que nous ne savons pas comment les rendre détectables. De plus, les développeurs, lorsqu'ils écrivent du code, savent qu'ils doivent écrire du code réutilisable mais manquent de motivation pour le faire.

Vous avez besoin d'une documentation appropriée. Il devrait être facile à trouver et à naviguer. Vous avez également besoin de discipline. S'il y a déjà une solution fournie dans vos bibliothèques de code réutilisables mais que le développeur choisit d'utiliser sa propre solution à la place (sans raison valable), vous devez revenir sur sa solution et lui dire d'utiliser la solution existante.

Je suis également d'accord avec le commentaire d'Euphoric sur la question. Il est souvent impossible de réutiliser quoi que ce soit entre différents projets (généralement toutes les opérations CRUD se ressemblent, mais vous ne pouvez généralement pas les réutiliser).

A côté des facteurs déjà mentionnés "documentation", "facile à trouver et à naviguer", "discipline" et "codereview"

le code réutilisable doit être

• facile à utiliser (= besoin d'exemples c.-à-d. non testés)
• sans trop de dépendances à d'autres modules et
• il doit avoir une api stable donc je n'ai pas besoin de mettre à jour mon application pour utiliser la bibliothèque.

sans les deux derniers éléments, il est beaucoup plus facile d'utiliser "la copie et l'héritage passé" dont nous ne voulons pas.

Je pense que la meilleure façon de leur faire réutiliser du code est la motivation. Si vous placez les composants réutilisables dans des projets supplémentaires, comme l'a suggéré Euphoric, mettez-y beaucoup d'efforts. Là où je travaille, nous avons fait un projet, qui exécute un ensemble d'interfaces prédéfinies dans des plans d'exécution configurables et fournit quelques services (par exemple différentes classes pour DB_interaction, un service FTP, ...). Le projet est un grand succès, car nos développeurs veulent réellement utiliser le micro-framework, car cela leur fait gagner beaucoup de temps pour écrire du code passe-partout pour des projets similaires. La même chose est pour les bibliothèques d'utilitaires pour les listes, les chaînes, etc., mais dans ce cas, vous voudrez utiliser une fois. (pourquoi réinventer le weel?)

Conclusion: laissez vos développeurs découvrir les avantages de composants réutilisables bien testés. Mais je suis également d'accord avec la réponse d'Andrzej Bobak: Beaucoup de choses ne sont pas réutilisables, car elles sont similaires, mais pas les mêmes.

Cela va être difficile, car les gens aiment écrire du nouveau code pour des composants simples et ils aiment le faire à leur façon. Il est beaucoup plus difficile d'exploiter une solution existante et de l'étendre que d'écrire une implémentation complètement nouvelle avec les nouvelles exigences. Ce qui doit être fait, comme cela a été dit, est de lancer un processus de révision du code au sein de l'équipe pour aider à identifier les situations où des composants existants auraient dû être utilisés / étendus au lieu d'un nouveau.

Vous devez également maintenir une documentation très bonne et complète afin que les gens puissent s'y référer et trouver facilement ce dont ils ont besoin. Si la documentation est incomplète ou désynchronisée avec la réalité, les gens ne seront pas motivés à la parcourir ou à l'améliorer.

En tant que chef d'équipe, vous devez également encourager les gens à se demander si un composant similaire existe avant de créer le leur et les diriger vers la documentation afin qu'ils puissent la rechercher. Bien sûr, le processus de révision du code le rattrapera si quelqu'un a manqué un composant existant, mais que se passe-t-il s'il a déjà mis 10 heures de développement dans sa propre implémentation? Vous devez éviter ces situations en appliquant un bon comportement de recherche dans l'équipe.

Nous avons rencontré ce problème sur un grand projet sur lequel je travaille actuellement. Nous avons eu une rotation de développeurs au cours des derniers mois, c'est aussi une base de code assez importante et même ceux qui ont été sur le projet depuis le tout début n'en connaissent pas chaque centimètre.

Bien que le code soit souvent bien écrit et divisé en petites parties avec des responsabilités uniques et que la documentation soit là, il est assez facile de manquer quelque chose qui a été fait. Les conventions de dénomination cohérentes aident beaucoup car il est facile de rechercher quelque chose dans n'importe quel IDE. La documentation peut être complète mais à mesure qu'elle s'allonge, il est un peu pénible de la lire.

Une chose que nous avons fait qui, à mon avis, a considérablement amélioré la situation a été l'introduction d'une chose que nous appelons les discussions sur la foudre . Chaque fois que quelqu'un écrit un morceau de code qui, selon lui, devrait être connu de l'équipe, une courte présentation (généralement de 5 à 15 minutes) est organisée. Nous essayons de le faire une fois par semaine. Les sujets ont tendance à varier, des nouvelles fonctionnalités et façons de gérer les problèmes complexes qui sont récemment apparus, aux approches de test / codage, composant réutilisable, aux discussions sur les fondements de l'application et sa refactorisation.

Certains sujets sont mentionnés dans des discussions similaires à l'échelle de l'entreprise. Nous l'avons trouvé un moyen assez efficace pour stimuler le partage des connaissances. Il est beaucoup plus facile de voir et de mémoriser une courte présentation et de savoir où chercher de la documentation supplémentaire ou à qui s'adresser pour obtenir de l'aide que de participer à des sessions de formation très longues et rarement tenues ou de simplement rester assis là, en lisant la documentation.

Les discussions à l'échelle de l'entreprise sont en fait arrivées en premier. Nous venons d'adopter cette approche pour le partage des connaissances spécifiques au projet et je pense que cela fonctionne plutôt bien.

La programmation en binôme accélère également la circulation des connaissances.

Je pense qu'il s'agit en fait de deux questions en une - je vais essayer de répondre aux deux.

1) Comment réduire le code en double dans une base de code.
Cela permet de nous rappeler les avantages de cette opération: cela entraîne moins de bogues en raison de la logique métier en double et moins de code à maintenir. La meilleure façon d'éviter que cela ne se produise est la communication - comme mentionné dans les autres réponses. Je suis tout à fait d'accord avec la recommandation d'utiliser des révisions de code avec la mise en garde supplémentaire que vous devez partager les responsabilités de révision de code de manière égale pour diffuser correctement les connaissances. Vous devez également utiliser des stand-ups quotidiens afin que les développeurs reconnaissent souvent quand quelqu'un essaie de résoudre un problème pour lequel il existe du code utile. Vous devriez également envisager l'association de code car elle augmente le partage des connaissances et aide à garder les programmeurs disciplinés.

Je recommanderais également de rapprocher vos développeurs le plus possible, de préférence dans la même pièce. Avec beaucoup de tableaux blancs et d'espace partagés. Envoyez-les ensuite pour les repas ensemble. Plus vos développeurs «se lient» mieux ils communiqueront entre eux.

Je ne suis pas d'accord avec la recommandation d'utiliser un wiki ou similaire au code du document. Quelle que soit la discipline des développeurs, la documentation dérivera du code d'origine. Une approche plus efficace consisterait à utiliser des spécifications par des exemples de tests de style. Ceux-ci documentent le code d'une manière qui indique clairement comment il doit être utilisé et vos tests échoueront si quelqu'un modifie le code sans changer les exemples.

Vous avez déjà une grande base de code avec beaucoup de code en double, vous devriez donc probablement travailler sur la refactorisation. Il peut être difficile de trouver du code en double qui n'a pas été coupé et collé. Donc plutôt que de faire cela, je vous suggère d'analyser votre historique des changements. Recherchez les fichiers qui changent souvent en même temps. Cela indiquera probablement des problèmes d'encapsulation si cela n'indique pas un code en double réel et vaut la peine d'être nettoyé de toute façon. Si vous pouvez également analyser votre historique de corrections de bogues par rapport à vos modifications de code, vous pouvez trouver des points d'accès particuliers où des corrections sont souvent nécessaires. Analysez ces points chauds et vous constaterez probablement que beaucoup d'entre eux sont dus à une logique métier en double qu'un développeur n'a changé qu'à un seul endroit sans se rendre compte qu'il devait être changé deux fois.

2) Comment devrions-nous aborder la création de widgets, composants, bibliothèques, etc. partagés qui peuvent ensuite être utilisés dans d'autres projets .
Dans ce cas, vous ne devriez pas essayer d'envelopper la logique métier mais de partager un code de cadre utile. Cela peut être un équilibre délicat car le coût de création et de maintenance d'un ensemble de composants partagés peut être assez important et il peut être difficile de prédire dans quels cas cela vaut la peine. L'approche que je suggérerais ici est une règle en trois temps. Ne vous inquiétez pas d'écrire deux fois un morceau de code similaire, mais lorsque vous devez le faire une troisième fois, refactorisez-le dans un composant partagé. À ce stade, vous pouvez être raisonnablement sûr qu'il sera utile et vous avez une bonne idée des exigences plus larges du composant. De toute évidence, la communication entre développeurs est vitale ici.

Envisagez de créer autant de composants partagés open source que possible. Ce n'est pas une logique commerciale, donc cela ne donnera pas beaucoup d'avantages à vos concurrents, mais cela signifie que vous obtiendrez gratuitement des réviseurs et des mainteneurs supplémentaires.

IMMO la clé n'est pas de la documentation ou des outils, la clé est la COMMUNICATION. 10+ développeurs ce n'est pas beaucoup de gens, certaines choses qui améliorent cette communication:

• programmation en binôme: avec deux personnes, il y a plus de changements que l'un des deux sait que le problème est déjà résolu dans une autre partie du projet et le réutilise.

• Propriété collective du code: Toutes les personnes travaillent avec les différentes parties des systèmes, de cette façon, il est beaucoup plus facile de savoir que quelque chose est déjà fait dans une autre partie du projet, pour moi, c'est une pratique fondamentale dans une équipe.

• Donnez du temps pour travailler sur des projets horizontaux: par exemple, un vendredi ou deux par mois, et les développeurs à cette époque peuvent travailler dans ses propres projets qui ont une certaine applicabilité à votre projet d'entreprise. De cette façon, les développeurs peuvent écrire des bibliothèques et des composants réutilisables, parfois son code existe déjà mais nécessite un nettoyage et une documentation.

• Faire des discussions et des ateliers: Réservez un temps pour les discussions et les ateliers des développeurs, les développeurs peuvent parler de ses bibliothèques ou peut-être faire des ateliers de refactorisation et prendre du code dupliqué et supprimer la duplication en créant un composant réutilisable.

La documentation est probablement nécessaire, mais ce n'est qu'une petite partie de la vraie chose dont vous avez besoin: améliorer la communication au sein de votre équipe.

Qu'en est-il de l'utilisation d'un moteur de recherche local tel que Lucene (ou quelque chose de plus spécifique au code source) pour indexer votre code? Quand quelqu'un commence à écrire une nouvelle classe ou une nouvelle fonction (par exemple), il doit essayer (comme politique interne) quelques recherches avant d'écrire son propre code. De cette façon, vous pouvez éviter trop de communications et vous pouvez compter sur de bons commentaires, méthodes et noms de classes. Je me retrouve à faire cela avec des moteurs de recherche open source disponibles sur Internet: je ne sais pas qui a écrit quoi ou quel est le nom d'une méthode ou d'une classe, mais avec quelques recherches ou synonymes, je trouve toujours ce dont j'ai besoin.

Vous avez besoin d'un outil qui aide vos développeurs à le faire de manière transparente. Si vos développeurs découvrent combien de temps ils peuvent gagner en réutilisant les extraits de code (non seulement en termes d'écriture du code, mais bien sûr pour l'assurance qualité, l'intégration, etc.), aidés par un outil efficace, facile à utiliser et directement intégrés dans l'environnement de développement, ils VOUS PRIERONT pour adopter un tel outil!

Attention, la réalisation de bibliothèques de réutilisation de code ne se traduira pas souvent par un énorme avantage (elles ont tendance à devenir trop puissantes et trop grandes ...); au lieu de cela, je voudrais me concentrer sur des extraits simples, c'est-à-dire quelques lignes de code qui résolvent une tâche particulière de manière efficace.

De cette façon, vous pouvez forcer l'utilisation des directives et des meilleures pratiques en donnant de vrais exemples qui peuvent être directement utilisés par les programmeurs.

Il existe plusieurs outils pour la gestion des extraits, je recommande celui-ci: http://www.snip2code.com .

(Avertissement: je suis l'un des fondateurs de Snip2Code, et j'étais - avec mes co-fondateurs - dans votre même état d'esprit il y a quelque temps: c'est pourquoi nous avons décidé de lancer ce projet, qui rassemble toutes les fonctionnalités que je indiqué ci-dessus, à savoir le partage d'extraits au sein d'une équipe, l'intégration dans des IDE tels que Visual Studio, Eclipse, IntelliJ, Notepad ++, etc.)