>
>
>
>
>
Informações de engenharia
>>
>
>
>
>
>
>
>
>
>>
Uma habilidade importante para qualquer engenheiro de software é escrever documentos de design técnico (TDDs), também referidos como documentos de design de engenharia (EDDs). Aqui neste artigo eu ofereço alguns conselhos para escrever bons documentos de design e que erros evitar.
Uma advertência: equipas diferentes terão padrões e convenções diferentes para o design técnico. Não existe um padrão industrial para o processo de design, nem poderia existir, pois diferentes equipes de desenvolvimento terão necessidades diferentes dependendo da sua situação. O que vou descrever é uma resposta possível, baseada na minha própria experiência.
Comecemos pelo básico: O que é um documento de desenho técnico, e como ele se encaixa no processo de desenho?
Um documento de desenho técnico descreve uma solução para um determinado problema técnico. É uma especificação, ou “design blueprint”, para um programa ou recurso de software.
A principal função de um TDD é comunicar os detalhes técnicos do trabalho a ser feito aos membros da equipe. Entretanto, há um segundo propósito que é igualmente importante: o processo de escrever o TDD força você a organizar seus pensamentos e considerar cada aspecto do design, assegurando que você não tenha deixado nada de fora.
Documentos de design técnico são freqüentemente parte de um processo maior que normalmente tem os seguintes passos:
- Requisitos do produto são definidos. Estes serão tipicamente representados por um Documento de Requisitos do Produto (PRD). O PRD especifica o que o sistema precisa fazer, a partir da perspectiva de um usuário ou agente externo.
- São definidos requisitos técnicos. Os requisitos do produto são traduzidos em requisitos técnicos – o que o sistema precisa fazer, mas agora como ele o faz. A saída desta etapa é um Documento de Requisitos Técnicos (TRD).
- Projeto técnico. Este contém uma descrição técnica da solução para os requisitos delineados nas etapas anteriores. O TDD é a saída desta etapa.
- Implementação. Esta é a etapa onde a solução é realmente construída.
- Testes. O sistema é testado em relação ao PRD e TRD para garantir que ele realmente atende aos requisitos especificados.
Entre cada uma dessas etapas, normalmente há um processo de revisão para garantir que não foram cometidos erros. Se quaisquer erros, mal-entendidos ou ambiguidades forem detectados, estes devem ser corrigidos antes de prosseguir para o próximo passo.
Este processo é altamente variável; o conjunto de passos listados aqui irá mudar caso a caso. Por exemplo:
- Para recursos menores que não envolvam muita complexidade, os passos 2 e 3 serão freqüentemente combinados em um único documento.
- Se o recurso envolver um grande número de desconhecidos ou algum nível de pesquisa, pode ser necessário construir uma implementação de prova de conceito antes de finalizar o projeto técnico.
Este processo também acontece em diferentes escalas e níveis de granularidade. Um PRD / TRD / TDD pode dizer respeito ao projeto de todo um sistema, ou apenas de uma única característica. Na maioria dos ambientes, o processo também é cíclico – cada ciclo de design/implemento se baseia no trabalho do anterior.
A linha divisória entre TRD e TDD pode ser um pouco desfocada às vezes. Por exemplo, suponha que você esteja desenvolvendo um servidor que se comunica através de uma API RESTful. Se o objetivo é estar em conformidade com uma API já estabelecida e documentada, então a especificação da API é parte dos requisitos e deve ser referenciada na TRD. Se, por outro lado, o objetivo é desenvolver uma API totalmente nova, então a especificação da API faz parte do projeto e deve ser descrita na TDD. (Entretanto, o documento de requisitos ainda precisa especificar o que a API está tentando realizar.)
Escrevendo a TDD
Nos dias atuais, é prática comum escrever documentos técnicos em um sistema de documentos colaborativos, como o Google Docs ou o Confluence; entretanto, isso não é um requisito absoluto. O importante é que haja uma forma de os membros da sua equipa poderem fazer comentários sobre o documento e apontar erros e omissões.
A maioria dos TDDDs tem entre uma e dez páginas. Embora não haja um limite superior para a extensão de uma TDD, documentos muito grandes serão difíceis de editar e difíceis de absorver pelos leitores; considere dividi-los em documentos separados, representando etapas ou fases individuais da implementação.
Diagramas são úteis; há várias ferramentas online que você pode usar para incorporar ilustrações no documento, como draw.io ou Lucidchart. Você também pode usar ferramentas offline como o Inkscape para gerar diagramas SVG.
O documento deve ser minucioso; idealmente, deve ser possível para alguém que não seja o autor do TDD implementar o design como escrito. Por exemplo, se o projeto especificar uma implementação de uma API, cada ponto final da API deve ser documentado. Se houver escolhas de design sutis, elas devem ser chamadas de out.
Evite Erros de Escrita Comum
Provavelmente o erro mais comum que eu encontro em TDDs é a falta de contexto. Ou seja, o autor escreveu, em poucas palavras, como resolveram o problema; mas não incluíram nenhuma informação sobre qual era o problema, porque precisava de ser resolvido, ou quais eram as consequências de escolher essa solução em particular.
Também, é importante ter em mente quem é o provável leitor, e que nível de compreensão eles têm. Se você usar um termo que o leitor possa não saber, não tenha medo de adicionar uma definição para ele.
Dificilmente será necessário dizer que uma boa gramática e ortografia são úteis. Além disso, evite a tentação do jogo de palavras ou da ortografia “bonitinha”; enquanto programadores como classe tendem a gostar de brincar com a linguagem, já vi mais de um caso em que a frivolidade excessiva acabou custando o esforço desperdiçado da equipe por causa de mal-entendidos. Não faz mal usar humor ocasional ou escolher nomes coloridos e memoráveis para características e sistemas, uma vez que isso ajuda as pessoas a lembrarem-se deles. Mas não deixe o seu desejo de mostrar o quão inteligente você é se tornar uma distração.
Dizer nomes, escolha-os cuidadosamente; como Mark Twain escreveu uma vez, “Escolha a palavra certa, não é primo em segundo grau”. Há uma tendência para engenheiros com vocabulário pobre usarem os mesmos termos genéricos uma e outra vez para coisas diferentes, levando a sobrecarga e confusão. Por exemplo, nomear uma classe “DataManager” é vago e não lhe diz nada sobre o que ela realmente faz; da mesma forma, um pacote ou diretório chamado “utils” pode conter praticamente qualquer coisa. Consulte um thesaurus se você precisa encontrar uma palavra melhor, ou melhor, uma base de dados de sinônimos especializados como WordNet.
TDD Template
Ao escrever um TDD, pode ser útil começar com um template padrão. O seguinte é um modelo que usei em vários projetos. Note que este template deve ser personalizado onde necessário; você é livre para apagar seções que não se aplicam, adicionar seções adicionais, ou renomear cabeçalhos como apropriado.