Modelos de Documentação para Software
6,183 views
Skip to first unread message
Charles Reitz
Apr 5, 2012, 1:41:53 PM4/5/12
to cfbr...@googlegroups.com
Bom Dia Pessoal!
Gostaria de desejar um Feliz Páscoa para todos, que Deus ilumine suas famílias.
Aproveitando, alguém tem algum exemplo de documentação tanto para banco de dados (normalmente eu comento no próximo banco utilizando o MYSQL WORKBENCH) como para versões do sistema(Utilizamos SVN mesmo assim queria algo documentos .doc), se caso alguém tiver alguns exemplos e conseguir enviar agradeço.
Minha idéia e deixar algo para os próximos programados que poderão vir, para não dizer "Não tem por onde começar" rsss..
Grande Abraço!
Anderson Straube
Apr 5, 2012, 2:16:24 PM4/5/12
to cfbr...@googlegroups.com
Fala Charles,
A melhor documentação que eu já vi é um código legível, com trechos comentados, etc... De nada adianta ter pilhas de papéis/documentos e quando o programador vai abrir o fonte é um spaghetti code... :)
Mas é claro, muitas vezes precisamos ter documentos. Para isso eu acho muito prático e simples a utilização de um wiki. Ele é um documento acessível por todos e qualquer um pode alterar quando ver alguma inconsistência, acredito que para manutenção funciona melhor do que um arquivo físico (tipo um .doc). O grande vilão que eu vejo nas documentações desse tipo é manter ela atualizada, pois fazer a primeira vez é relativamente simples.
Quando falo em wiki me refiro a documentação a nível de regras de negócio e lógicas e/ou particularidades do sistema, já para código eu prefiro ter comentários em cima dos métodos e alguns blocos que podem gerar dúvidas, além é claro de utilizar sempre a tag "hint".
Se você tiver as tags comentadas em seu código (como citei anteriormente) você pode gerar uma documentação do teu sistema ao estilo "Javadoc".
Aconselho dar uma olhada nesses links:
http://code.google.com/p/cfcdoc/
http://cftag.riaforge.org/
Abraços.
A melhor documentação que eu já vi é um código legível, com trechos comentados, etc... De nada adianta ter pilhas de papéis/documentos e quando o programador vai abrir o fonte é um spaghetti code... :)
Mas é claro, muitas vezes precisamos ter documentos. Para isso eu acho muito prático e simples a utilização de um wiki. Ele é um documento acessível por todos e qualquer um pode alterar quando ver alguma inconsistência, acredito que para manutenção funciona melhor do que um arquivo físico (tipo um .doc). O grande vilão que eu vejo nas documentações desse tipo é manter ela atualizada, pois fazer a primeira vez é relativamente simples.
Quando falo em wiki me refiro a documentação a nível de regras de negócio e lógicas e/ou particularidades do sistema, já para código eu prefiro ter comentários em cima dos métodos e alguns blocos que podem gerar dúvidas, além é claro de utilizar sempre a tag "hint".
Se você tiver as tags comentadas em seu código (como citei anteriormente) você pode gerar uma documentação do teu sistema ao estilo "Javadoc".
Aconselho dar uma olhada nesses links:
http://code.google.com/p/cfcdoc/
http://cftag.riaforge.org/
Abraços.
-- [ ]'s Anderson Straube http://www.astraube.eti.br
--
Você recebeu este e-mail pois está cadastrado na lista ColdFusion Brasil
Para CANCELAR sua assinatura escreva para cfbrasil+u...@googlegroups.com
Para ASSINAR a lista escreva para cfbrasil+...@googlegroups.com
O endereço para ENVIO DE MENSAGENS da lista é cfbr...@googlegroups.com
REGRAS em http://groups.google.com/group/cfbrasil/web/regras-de-boa-convivncia-na-lista
Outras opções disponíveis em http://groups.google.com/group/cfbrasil
Anderson Straube
Apr 5, 2012, 3:34:29 PM4/5/12
to cfbr...@googlegroups.com
Charles,
Esqueci de comentar sobre o banco de dados:
Sobre isso eu acredito que uma boa modelagem do sistema (DER | MER) já ajuda e muito.
Não citei também os demais documentos como: casos de uso, diagrama de classes, diagrama de sequência (UML) e tudo mais... porém acho que muitas delas é desnecessário se você tem outras alternativas mais práticas e menos custosas para dar manutenção. Mas é claro, muitas pessoas não conseguem se adaptar a algumas formas, por isso o fator que eu julgo mais importante de tudo é você e/ou sua empresa ter um padrão, seja ele qual for.
Abraço.
Esqueci de comentar sobre o banco de dados:
Sobre isso eu acredito que uma boa modelagem do sistema (DER | MER) já ajuda e muito.
Não citei também os demais documentos como: casos de uso, diagrama de classes, diagrama de sequência (UML) e tudo mais... porém acho que muitas delas é desnecessário se você tem outras alternativas mais práticas e menos custosas para dar manutenção. Mas é claro, muitas pessoas não conseguem se adaptar a algumas formas, por isso o fator que eu julgo mais importante de tudo é você e/ou sua empresa ter um padrão, seja ele qual for.
Abraço.
Rafael Bandeira Rodrigues
Apr 6, 2012, 7:12:11 AM4/6/12
to cfbr...@googlegroups.com
Fala Charles,
Cara documentação é algo que deve ser responsabilidade de uma pessoa especializada nisso e não do programador, senão afeta produtividade, mas como as empresas preferem perder produtividade a investir em qualidade da esses problemas que o Anderson comentou, documentos desatualizados etc, etc.
Se você faz seus projetos utilizando OO de forma correta, recomendo o cfc2uml (http://cfc2uml.riaforge.org/) ele gera o diagrama de classes e a partir dele, fica mai facil gerar caso de uso, sequencia etc.
Para o DB eu gosto muito do M$ Visio porque ele integra com o SQL Server e Oracle, que são os DB's que a gente mais usa por aqui. E funciona no mesmo modelo integrado. Com isso o trabalho passa a ser de gerar um PDF atualizado toda vez que aparece um programador novo, garantindo a última versão.
Como o Andreson também falou, nada adianta documentação certinha se o framework de trabalho se chama "Macarronada da mama" porque ele vai conhser os CFC's, o modelo do DB mas vai perder dias para achar as entradas dos fontes, então é bom além de pensar em documentação, planejar uma arquitetura e padrão de código, um framework ou algo do tipo sempre acabam ajudando.
Obrigado,
Rafael Bandeira Rodrigues
Chief Executive Officer
FlagNet - Soluções em Tecnologia
http://www.flagnet.inf.br/
Adobe ColdFusion 8 Certified Expert
Adobe ColdFusion MX 7 Certified Developer
Adobe Certified Professional
Adobe Certified Instructor
Adobe Certified Expert
Fusebox - BRASIL
http://www.fusebox.com.br/
RafaBand - BlogSpot.com
http://rafaband.blogspot.com/
FlagNet - Twiter
http://twitter.com/flagnet/
"Pensar apenas ou desejar somente nunca levou ninguém a lugar nenhum. É necessário também a ação" - William Shakespeare
Cara documentação é algo que deve ser responsabilidade de uma pessoa especializada nisso e não do programador, senão afeta produtividade, mas como as empresas preferem perder produtividade a investir em qualidade da esses problemas que o Anderson comentou, documentos desatualizados etc, etc.
Se você faz seus projetos utilizando OO de forma correta, recomendo o cfc2uml (http://cfc2uml.riaforge.org/) ele gera o diagrama de classes e a partir dele, fica mai facil gerar caso de uso, sequencia etc.
Para o DB eu gosto muito do M$ Visio porque ele integra com o SQL Server e Oracle, que são os DB's que a gente mais usa por aqui. E funciona no mesmo modelo integrado. Com isso o trabalho passa a ser de gerar um PDF atualizado toda vez que aparece um programador novo, garantindo a última versão.
Como o Andreson também falou, nada adianta documentação certinha se o framework de trabalho se chama "Macarronada da mama" porque ele vai conhser os CFC's, o modelo do DB mas vai perder dias para achar as entradas dos fontes, então é bom além de pensar em documentação, planejar uma arquitetura e padrão de código, um framework ou algo do tipo sempre acabam ajudando.
Obrigado,
Rafael Bandeira Rodrigues
Chief Executive Officer
FlagNet - Soluções em Tecnologia
http://www.flagnet.inf.br/
Adobe ColdFusion 8 Certified Expert
Adobe ColdFusion MX 7 Certified Developer
Adobe Certified Professional
Adobe Certified Instructor
Adobe Certified Expert
Fusebox - BRASIL
http://www.fusebox.com.br/
RafaBand - BlogSpot.com
http://rafaband.blogspot.com/
FlagNet - Twiter
http://twitter.com/flagnet/
"Pensar apenas ou desejar somente nunca levou ninguém a lugar nenhum. É necessário também a ação" - William Shakespeare
Ricardo Araujo
Apr 8, 2012, 8:29:00 PM4/8/12
to cfbr...@googlegroups.com
Pois é,
--
Aquele Abraço,
Ricardo Araujo
mas tem o outro lado,
dizem que construir um software não é como construir um predio e sim como criar um prato gastronomico, onde vc so sabe a receita depois de pronto, e ai sim poder replicar e explicar o conhecimento do software
Metodologias Ageis dizem para fazer apenas a documentaçao necessaria para o desenvolvimento, o resto se faz depois de pronto.
se puderem da uma olhada no blog http://improveit.com.br/xp la tem um video de uma palestra bem legal do Vinicius Teles que vale a pena todos assistirem.
2012/4/6 Rafael Bandeira Rodrigues <rafa...@gmail.com>
Aquele Abraço,
Ricardo Araujo
Reply all
Reply to author
Forward
0 new messages