J'ai rejoint le milieu d'un projet de taille moyenne, qui se déroule déjà depuis plusieurs années. L'un des problèmes est que le document décrivant l'architecture n'a jamais été écrit. Je suis affecté une tâche d'écrire la description de l'architecture.

Pendant le temps que j'ai travaillé sur ce projet, j'ai rassemblé toutes les informations dont j'avais besoin pour rédiger le document. Depuis que j'ai également ajouté quelques fonctionnalités, j'ai identifié des morceaux de code qui cassent clairement l'architecture telle qu'elle est décrite.

Par exemple, l'interface utilisateur graphique était censé être une fine couche, sans logique d'affaires. C'est ce qu'on m'a dit. L'implémentation contient beaucoup de logique.

Mon patron m'a confié la tâche, d'écrire le document décrivant l'architecture du système. Le public cible est les développeurs actuels et futurs travaillant sur le projet. J'ai besoin de décrire ce qui devrait être, mais j'ai aussi besoin de décrire les écarts d'une manière ou d'une autre.

Alors, où dois-je décrire ces problèmes? Logiciel de suivi des bugs? Ou dois-je décrire les écarts de mise en œuvre par rapport à l'architecture dans le document décrivant l'architecture du système?

Si vous documentez une conception ou une architecture d'un système qui a déjà été construit, le document doit le décrire tel que construit et non tel que conçu ou tel que prévu. S'il y a des bizarreries ou des divergences dans l'architecture, alors ce document devrait signaler ces problèmes et les expliquer autant que possible à un lecteur.

Si vous pouvez obtenir des informations de personnes qui ont travaillé sur le système depuis le début (ou au moins plus longtemps que vous), il serait utile de capturer plus d'informations sur ce qui était réellement prévu et pourquoi l'architecture et la conception s'en sont écartées. intention.

À la fin de la journée, un document de conception devrait servir de guide pour le code. Si le document ne permet pas un nouveau développeur à comprendre l'état de la base de code et comment il est structuré, que le document est inutile.

Ce document doit être un document évolutif qui est utilisé pour guider la planification future et la conception des modifications au système et ensuite mis à jour, dans le processus de développement. Alors que les modifications de conception et évolue au fil du temps, le document devrait également aider les concepteurs à comprendre pourquoi les choses sont comme elles sont actuellement.

Si vous cherchez des conseils sur la capture de l'architecture, j'aime l'approche préconisée dans la norme IEEE 1016-2009 Norme IEEE pour les technologies de l'information - Conception de systèmes - Description de conception de logiciels . Il fournit une structure raisonnable pour une description de conception, qui peut être utilisée pour capturer à la fois des informations de conception au niveau architectural et détaillé.

Je considérerais également ces écarts comme une forme de dette technique. Il peut s'agir d'une entreprise importante, peut-être même d'un petit projet, pour résoudre les problèmes, je recommanderais de rendre plus visible l'existence de la dette technique. Si cela signifie que vous utilisez l'outil de suivi des défauts, alors vous pouvez mettre une ou plusieurs questions là-bas. Si vous avez un autre outil que vous utilisez pour suivre les suggestions et les améliorations du logiciel, cela peut être un autre endroit pour le mettre.

Lors de la formalisation de l'architecture du système, il est important que vous compreniez non seulement la valeur derrière ce que l'architecture apportera à la table, mais aussi de comprendre et d'apprécier ce qu'elle devrait être.

Les principaux objectifs du logiciel ou de l'architecture technique sont d'identifier les exigences non fonctionnelles qui sont réalisées par les attributs de qualité qui guideront l' architecture du système .

Sur les exigences non fonctionnelles:

Une exigence non-fonctionnelle est un besoin qui précise les critères qui peuvent être utilisés pour juger de l'exploitation d'un système, plutôt que des comportements spécifiques. Ils sont mis en contraste avec les exigences fonctionnelles qui définissent le comportement ou des fonctions spécifiques. Le plan de mise en œuvre des exigences fonctionnelles est détaillé dans la conception du système. Le plan de mise en œuvre des exigences non-fonctionnelles sont détaillées dans l'architecture du système.

D'une manière générale, les exigences fonctionnelles définissent ce qu'un système est censé faire et les exigences non fonctionnelles définissent comment un système est censé être. ... exigences non-fonctionnelles sont souvent appelés « critères de qualité » d'un système. D'autres termes pour les exigences non fonctionnelles sont les «qualités», les «objectifs de qualité», les «exigences de qualité de service», les «contraintes» et les «exigences non comportementales».

Bien sûr, l'identification des exigences architecturales importantes est logique dans le cadre d'un projet entièrement nouveau, mais lorsque vous travaillez avec des logiciels existants, il est préférable d'être aussi discipliné que possible. Vous ne voudrez pas votre architecture logicielle se laisser influencer par le système actuel.

L'architecture logicielle pour faire autorité doit vraiment être 3 choses.

Déclaratif

C'est la partie de la documentation où vous déclarez PAS CE QUI EST, mais comment les choses DEVRAIENT ÊTRE. Nous y parvenons grâce à l'utilisation de différentes vues d'architecture du système. On définit les éléments qui devraient être, la façon dont ils interagissent, et nous percer le cas échéant vers le bas dans chaque composante des vues plus précises qui déclarent meilleure manière de concevoir le système.

Cette distinction est importante. La conception du système doit être limitée par l'architecture du système, ce sont en fait des choses distinctes mais liées.

Raisonnement

La raison d'être de votre architecture logicielle est ce qui donne une légitimité et l'autorité aux décisions d'architecture qui ont été faites. Peut-être il a été décidé d'utiliser un événement Publicité / Sous auditeur sur MQ de déclenchement d'un traitement par lots et vous diagramme, il?

Pourquoi cette décision? Nous expliquons pourquoi dans la section Raison d'être et un lien vers notre explication exigences non fonctionnelles, de qualité objectifs d'attributs, ou point de vue architectural principales exigences. (Ex. Les emplois doivent être asynchrone et reproductible, maintenabilité en tant que lecteurs d'attributs de la qualité que dans le cas d'un échec de traitement par lots que les emplois peuvent être ré-émis par l'intermédiaire d'un message MQ, le système doit avoir zéro perte de message à la communication asynchrone, etc. ..)

Des risques

Maintenant que vous avez déclaré comment l'architecture devrait être et que vous l'avez prouvée avec votre justification, vous pouvez maintenant identifier les risques sur l'état actuel du système là où cela ne demeure pas.

(Par ex. Validation côté serveur est dupliqué sur le côté client du code Javascript. Ceci est une violation du principe de SEC et ce qui est contraire à l'attribut qualité de maintenabilité. Il n'y a pas d'exigences non fonctionnelles définies environ Performances dans ce domaine il n'y a ne justifie le comportement du système courant)

Vos risques peuvent diagramme dans lequel l'état courant est en écartons de l'Architecture. Ces risques peuvent être traités par l'équipe de développement dès maintenant, soit par le biais de leur plan de projet, soit en l'ajoutant au carnet de commandes.

Vous avez vraiment besoin de décider si vous êtes censé être documentant la courant structure du projet, ou la désirée structure du projet, ou les deux.

Vous pouvez documenter l'objectif, dans le but d'orienter le développement futur le long des lignes souhaitées, et augmenter les écarts en tant que bogues (peut-être un lien vers ces bogues à partir des parties pertinentes du document). Ou vous pouvez documenter la réalité afin de fournir une introduction / un aperçu du code. Ou vous pouvez documenter les deux côte à côte, afin d'avoir simultanément un guide pour le développement futur et une description précise du code courant dans un endroit. Tous sont raisonnables selon ce que le document est censée être car, donc je ne pense pas que nous pouvons utilement vous dire que l' on à faire.

Vous devez également tenir compte du fait que la désirée l' architecture ne soit pas d' accord universel entre les acteurs (soit parce qu'ils veulent des choses différentes, ou parce que certains d'entre eux ont compris que des souhaits partagés originaux étaient impossibles ou peu pratique et donc recours à l' écriture du code existant divergeant de l'objectif). Vous devez donc également savoir si vous avez ou non le pouvoir de décider de ce qui est souhaité, et si ce n'est pas le cas. La structure existante a au moins le mérite de n'en avoir qu'une seule à documenter!

Ecrire dans le Document de conception de l'architecture ce qui était censé être, et pour chaque conflit vous trouvez ouvrir un sujet du bug tracker qui décrit le conflit. La section des commentaires du billet offrira une plate-forme pour les personnes concernées pour discuter ce conflit particulier.

Notez que la résolution de chacun de ces billets peuvent être de changer la mise en œuvre en fonction de la conception - mais il peut aussi être de changer la conception pour correspondre à la mise en œuvre. Idéalement, le premier est préféré, parfois il y a des techniques et / ou contraintes de l'entreprise qui le rend plus efficace / pragmatique / possible de choisir le plus tard. Dans ce cas, il peut être judicieux de se référer au ticket du document de conception d'architecture, afin que les futurs lecteurs qui ne comprennent pas pourquoi ce choix de conception inférieur particulier a été choisi puissent lire la discussion dans le ticket et comprendre le raisonnement derrière il.

Je serais tenté d'écrire un document d'architecture organisé en 3 sections principales.

Le premier présentant le design / l'architecture qui était initialement prévu. Elle permettra aux nouveaux concepteurs / lecteurs d'avoir une idée de ce que le système est censé faire et doit évidemment être liée aux exigences / usecases etc.

La deuxième partie doit expliquer clairement exactement ce que l'architecture en fait est. Cela permet aux nouveaux développeurs / lecteurs de se faire une idée de l'état actuel des choses et de ce à quoi ils ont affaire s'ils regardent le logiciel (et éventuellement d'autres documents). Cette section doit indiquer clairement la différence entre ce qui a été prévu et la réalité car cela va très probablement les êtres Hightlight qui soit très mal à l'architecture d' origine (espérons pas trop!) Et les zones où raccourcis / hacks (peut - être un juste peu s'il était une forte pression sur l'équipe de développement) a été exercée et les exigences ne sont pas remplies ou le logiciel commence à avoir l'air «mal» conçu, c'est-à-dire fragile, instable, non portable.

Enfin, je pense une section détaillant les recommandations pour ce qui doit se passer maintenant. Cela devrait être tout changement à l'architecture / conception et une feuille de route pour des modifications au logiciel actuellement afin de faire de votre vision devienne une réalité.

Je pense que cela couvre (à haut niveau) ce qui doit être capturé. Comment vous faites cela au niveau des sous-sections du texte ou un logiciel de suivi des bogues que vous employez est vers le domaine travaillez / préférences / size équipe / budgétaire / échelle de temps, etc.