Entrei no meio de um projeto de tamanho médio, que já dura vários anos. Um dos problemas é que o documento que descreve a arquitetura nunca foi escrito. Agora me foi atribuída uma tarefa para escrever a descrição da arquitetura.

Durante o tempo em que trabalhei neste projeto, reuni todas as informações necessárias para escrever o documento. Como também adicionei alguns recursos, identifiquei alguns trechos de código, que claramente estão quebrando a arquitetura, conforme descrito.

Por exemplo, a GUI deveria ser uma camada fina, sem lógica de negócios. Foi o que me disseram. A implementação contém muita lógica.

Meu chefe me designou a tarefa de escrever o documento descrevendo a arquitetura do sistema. O público-alvo são desenvolvedores atuais e futuros trabalhando no projeto. Eu preciso descrever o que deveria ser, mas também preciso descrever os desvios de alguma forma.

Então, onde devo descrever esses problemas? Software de rastreamento de bugs? Ou devo descrever os desvios da implementação da arquitetura no documento que descreve a arquitetura do sistema?

Se você estiver documentando um design ou arquitetura de um sistema que já foi construído, o documento deve descrevê-lo como construído e não como projetado ou como pretendido. Se houver estranhezas ou discrepâncias na arquitetura, este documento deverá chamar esses problemas e explicá-los o máximo possível para um leitor.

Se você puder obter informações de pessoas que trabalharam no sistema desde o início (ou pelo menos mais do que você), seria útil capturar mais informações sobre o que realmente era pretendido e por que a arquitetura e o design se desviaram disso. intenção.

No final do dia, um documento de design deve servir como um guia para o código. Se o documento não ajudar um novo desenvolvedor a entender o estado atual da base de código e como está estruturada, o documento não será útil.

Este documento deve ser um documento ativo usado para orientar o planejamento futuro e o design de alterações no sistema e, em seguida, atualizado de acordo com o processo de desenvolvimento. À medida que o design muda e evolui com o tempo, o documento também deve ajudar os desenvolvedores a entender por que as coisas estão do jeito que estão no momento.

Se você estiver procurando conselhos sobre como capturar a arquitetura, eu gosto da abordagem preconizada no IEEE Standard 1016-2009 IEEE Standard for Information Technology - Design de sistemas - Descrição do design de software . Ele fornece uma estrutura razoável para uma descrição do projeto, que pode ser usada para capturar informações de projeto em nível de arquitetura e detalhe.

Eu também consideraria esses desvios uma forma de dívida técnica. Pode ser uma grande empresa, talvez até um projeto pequeno, para corrigir os problemas, eu recomendaria tornar a existência da dívida técnica mais visível. Se isso significa que você usa sua ferramenta de rastreamento de defeitos, pode colocar um ou mais problemas lá. Se você possui outra ferramenta usada para rastrear sugestões e aprimoramentos do software, esse pode ser outro local para colocá-lo.

Ao formalizar a arquitetura do sistema, é importante entender não apenas o valor por trás do que a arquitetura trará para a mesa, mas também entender e apreciar o que deve ser.

Os principais objetivos do software ou da arquitetura técnica são identificar os requisitos não funcionais que são atendidos pelos atributos de qualidade que conduzirão a arquitetura do sistema .

Sobre requisitos não funcionais:

Um requisito não funcional é um requisito que especifica critérios que podem ser usados ​​para julgar a operação de um sistema, em vez de comportamentos específicos. Eles são contrastados com os requisitos funcionais que definem comportamentos ou funções específicas. O plano para implementar requisitos funcionais é detalhado no design do sistema. O plano para implementar requisitos não funcionais é detalhado na arquitetura do sistema.

Em termos gerais, os requisitos funcionais definem o que um sistema deve fazer e os requisitos não funcionais definem como um sistema deve ser. ... Requisitos não funcionais são freqüentemente chamados de "atributos de qualidade" de um sistema. Outros termos para requisitos não funcionais são "qualidades", "objetivos de qualidade", "requisitos de qualidade de serviço", "restrições" e "requisitos não comportamentais"

É claro que identificar os requisitos significativos da arquitetura faz sentido quando em um projeto greenfield; no entanto, ao trabalhar com o software existente, é melhor ser o mais disciplinado possível. Você não deseja que sua arquitetura de software seja influenciada pelo sistema existente.

A arquitetura de software para ser autorizada realmente precisa ser de três coisas.

Declarativo

Esta é a parte da documentação em que você declara NÃO O QUE É, mas como as coisas deveriam ser. Fazemos isso através do uso de várias vistas arquitetônicas do sistema. Definimos os componentes que devem ser, como eles interagem e, opcionalmente, detalhamos cada componente para obter visualizações mais granulares que declaram como o sistema deve ser projetado.

Esta é uma distinção importante. O design do sistema deve ser restringido pela arquitetura do sistema, eles são de fato coisas separadas, mas relacionadas.

Fundamentação

A justificativa da sua arquitetura de software é o que fornece legitimidade e autoridade às decisões de arquitetura que foram tomadas. Talvez tenha sido tomada a decisão de utilizar um ouvinte de evento Pub / Sub no MQ para acionar um trabalho em lotes e você o diagrama?

Por que essa decisão foi tomada? Explicamos o porquê na seção Justificativa e vinculamos nossa explicação a Requisitos Não Funcionais, Metas de Atributos de Qualidade ou Requisitos Arquitetônicos Significativos. (Por exemplo, os trabalhos devem ser assíncronos e repetíveis, a Manutenção como um atributo de qualidade leva a que, no caso de uma falha no trabalho em lote, os trabalhos possam ser reiniciados por meio de uma mensagem do MQ. O sistema deve ter Zero Message Loss com comunicação assíncrona etc. ..)

Riscos

Agora que você declarou como a arquitetura deve ser e a provou com o seu Rationale, agora pode identificar Riscos no estado atual do sistema para onde isso não ocorre.

(Por exemplo, a validação do servidor está sendo duplicada no código Javascript do cliente. Isso é uma violação do princípio DRY e isso contraria o Atributo de Qualidade de Manutenção. Não há requisitos não-funcionais definidos em relação ao Desempenho nesta área. (não há justificativa para o comportamento atual do sistema)

Seus riscos também podem esquematizar onde o estado atual está atualmente divergindo da arquitetura. Esses riscos podem ser tratados pela equipe de desenvolvimento agora, através do plano do projeto ou adicionando-os ao backlog.

Você realmente precisa decidir se deve documentar a estrutura atual do projeto, ou a estrutura desejada do projeto, ou ambos.

Você pode documentar a meta, com o objetivo de orientar o desenvolvimento futuro ao longo das linhas desejadas e aumentar os desvios como erros (talvez vincule-os a partes relevantes do documento). Ou você pode documentar a realidade para fornecer uma introdução / visão geral do código. Ou você pode documentar os dois lado a lado, para ter simultaneamente um guia para desenvolvimento futuro e uma descrição precisa do código atual em um só lugar. Todos são razoáveis, dependendo da finalidade do documento, portanto, acho que não podemos lhe dizer com utilidade qual deles deve ser feito.

Você também deve ter em mente que a arquitetura desejada pode não ser universalmente aceita entre os envolvidos (seja porque eles querem coisas diferentes ou porque alguns deles perceberam que alguns desejos compartilhados originais eram impossíveis ou impraticáveis ​​e, portanto, recorreram à escrita do código existente que se desvia do objetivo). Então, você também precisa saber se tem ou não autoridade para decidir o que é desejado e, se não, quem o faz. A estrutura existente tem pelo menos a virtude de que há apenas uma para documentar!

Escreva no documento de design da arquitetura o que deveria ser e, para cada conflito que você encontrar, abra um ticket no rastreador de erros que descreve o conflito. A seção de comentários do ticket oferecerá uma plataforma para as pessoas relevantes discutirem esse conflito específico.

Observe que a resolução de cada um desses tickets pode ser alterar a implementação para corresponder ao design - mas também pode ser alterar o design para corresponder à implementação. Idealmente, o primeiro é o preferido, mas às vezes existem restrições técnicas e / ou comerciais que tornam mais eficiente / pragmático / possível escolher o posterior. Nesse caso, pode ser uma boa ideia consultar o ticket do documento de design da arquitetura, para que futuros leitores que não entenderem por que essa escolha de design inferior em particular tenha sido escolhida possam ler a discussão no ticket e entender o raciocínio por trás isto.

Eu estaria inclinado a escrever um documento arquitetônico organizado em três seções principais.

A primeira introdução do design / arquitetura que foi inicialmente planejado. Isso permitirá que novos desenvolvedores / leitores tenham uma idéia do que o sistema deve fazer e obviamente devem estar vinculados aos requisitos / casos de uso etc.

A segunda seção deve explicar muito claramente exatamente o que a arquitetura realmente é. Isso permite que os novos desenvolvedores / leitores tenham uma idéia do estado atual do jogo e com o que estão lidando se analisarem o software (e potencialmente outra documentação). Esta seção deve indicar claramente a diferença entre o que foi planejado e a realidade, pois isso provavelmente irá destacar coisas que estão muito erradas com a arquitetura original (espero que não sejam muitas!) E áreas onde atalhos / hacks (provavelmente alguns se houver) uma grande pressão sobre a equipe de desenvolvimento) foi feita e os requisitos não estão sendo atendidos ou o software está começando a parecer 'mal' projetado, ou seja, frágil, instável, não portátil.

Finalmente, acho que uma seção detalhando as recomendações para o que precisa acontecer agora. Devem ser quaisquer alterações na arquitetura / design e um roteiro para alterações no software atualmente, a fim de tornar sua visão realidade.

Eu acho que isso cobre (em alto nível) o que precisa ser capturado. Como você faz isso em termos das subseções do documento ou do software de rastreamento de bugs que você emprega está no domínio em que você está trabalhando / preferência pessoal / tamanho da equipe / orçamento / escala de tempo etc.