Pessoal, sempre fizemos sistemas na base somente da codificação, ou seja, nos reuniamos e chegavamos a um acordo sobre determinada coisa e já metia a mão no código.
Nunca fiz uma documentação ou segui uma documentação para desenvolvimento e gostaria de documentar meus projetos para pelo menos, la na frente, relembrar algo que foi discutido e que não se lembrava como foi feito.
O que devo seguir? Nao quero fazer documentação apenas por dizer que tenho documentação do sistema, mesmo porque, geralmente cada sistema sofre mudanças ao longo de seu desenvolvimento e tenho certeza que nao iremos alterar documentação quando houver mudança.
Uma coisa importante a mencionar é que minha empresa nao cria sistemas para fora, criamos nosso sistema e vendemos serviço através dele. Neste caso, o “cliente” seria nós mesmos.
Estou meio perdido quanto a isso, da maneira que expliquei como andam as coisas em minha empresa, o que poderia ser a melhor opção a seguir nao investindo muito tempo em documentação, mas por outro lado, ter o sistema escrito de forma a sanar dúvidas futuras e até mesmo, servir como base para um manual de uso…
Como li esses dias no twitter: "Faça uma função funcionar, e depois refatore-a até quase não funcionar novamente."
Capriche nos javadocs, e providencie um wiki para sua equipe, onde vcs documentam os pontos chaves e conceitos do sistema de maneira interativa.
Se for fazer UML, use de partes chave do código, e providencie geradores automáticos.
A menos que seu sistema seja gigantesco e muito integrado (como um SAP), não vale a pena gastar horas e horas colocando tudo na UML. Até pq como vc mesmo observou, o custo de manter isso atualizado também é astronômico.
Atualmente estou trabalhando na melhoria da eficiência do pessoal de desenvolvimento da minha empresa, e isto consiste em inserir algumas práticas e conhecimentos no dia-a-dia da galera. Com esta tendência dos métodos ágeis, todo mundo fica ansioso pra melhorar. Basicamente, o que estou executando aqui é o seguinte, nesta sequência:
1- Ensinando conceitos básicos de TDD e instruindo o pessoal a desenvolver código testável e na medida do possível refatorar código legado para ser testável.
2 - Com a número 1 você já melhora a noção de design de aplicações OO de forma absurda
3 -Criei um repositório SVN (acreditem, nem isso tinha) e todo mundo comita lá. Criei um script de build que compila e roda os testes unitários criados no passo 1.Também inclui no script uma ferramenta para cobertura de código. O pessoal roda isso localmente antes de comitar
4 - Instalamos um servidor de IC que roda o mesmo build e mostra as quebras , bem como o percentual de cobertura de código. Coloquei um limite mínimo de 80%
5 - E a documentação? Bom, estamos tentando escrever nossos requisitos com cara de BDD e incluímos isto na ferramenta de issue-tracking. Cada feature tem um critério de aceitação e com isso a ferramenta já gera bastante documentação funcional. Sem contar que o próprio servidor já testa, já aprova ou reprova e gera um retrato atual do projeto. O restante de documentação de design e arquitetura também é puxado das ferramentas direto do código.
6 - Colocamos também um wiki para compartilhar informações técnicas livremente.
Próximos passos:
Implantar uma ferramenta de métricas de código , tipo Sonar
Implantar automatização de testes de tela , com algo tipo Selenium
Quanto a documentação, você deve alterá-la sempre que fizer uma alteração no projeto sim! Já pensou? Se alguém modifica uma funcionalidade, adiciona propriedades e não documenta? E quando no sistema começar a surgir bugs? (o que vai acontecer)
Deve estar tudo na documentação, até porque, muitas vezes não é o mesmo programador que irá concertar aquele erro. E mesmo se for, talvez nem se lembre como aquela alteração inicial foi feita. Por essas e outras, que a documentação é essencial (e a atualização dela também).
Realmente documentação é muito importante. No entanto o esforço para documentar tudo as vezes é muito grande, o bom de usar boas ferramentas como estas que citei é que boa parte das tarefas braçais de documentação são feitas de forma automática, pela própria ferramenta.
Seria ótimo se vc pudesse desenvolver de forma iterativa e incremental.
Faça um esboço do projeto (uns scaffolds do rails seriam interessantes) sem css bonito nem nada. É isso mesmo que o cliente quer? Se sim, vai melhorando.
Infelizmente nem sempre é possivel desenvolver assim e se não tiver gente experiente no projeto a chance de dar m… é grande. Mas é uma forma de pensar, se for possivel usar o conceito faça um teste. De repente o sistema todo é bem conhecido (um ERP por exemplo) mas uma parte dele (um relatorio, sei la) pode ser desenvolvido assim.
O importante é falhar rapido e corrigir, não dá pra ficar 8 meses escrevendo .doc do word e diagrama uml pra descobrir q não é nada daquilo.
Documentação é algo muito importante. Isso auxilia a outros desenvolvedores a dar manutenção no código e ate você mesmo.
A UML considero ela muito importante durante a fase de projeto e desenvolvimento de sistemas, pois durante o desenvolvimento dependendo da complexidade do problema, a resolução através de uma diagrama, como por exemplo, diagrama de atividades ou estados, ajuda, mesmo que estes sejam descartados depois.
É como o ViniGodoy disse: “use de partes chave do código, e providencie geradores automáticos.”
Eu atualmente trabalho com o sistema da Microsiga - Protheus 10, a cada customização que realizamos sempre documentamos e caso seja necessário o diagrama UML.
Documentar os requisitos de sistema também ajuda e muito durante o desenvolvimento do sistema, pois requisitos ao longo do sistema constantemente estão mudando.