Neste artigo quero dar uns toques para aqueles que estão iniciando no mundo da programação a colocar em seus programas e scripts informações úteis para ajudar não só na documentação, mas também no desenvolvimento dos mesmos.
Quando você escreve um programa, a não ser que você esteja escrevendo para consumo próprio, você vai ter a oportunidade de que outras pessoas vejam, usem e avaliem.
Principalmente aqui no VOL, você está colocando em exposição não só a sua boa vontade em ajudar os outros com a publicação de programas gratuitos, mas também que podem ser a base para novos programas.
Então quando você olha o código fonte deles, algumas coisas ajudam muito na colaboração e o desenvolvimento deste programa.
[1] Comentário enviado por rodolfocoutinho em 25/01/2008 - 11:39h
Um dos principais problemas se dá quanto a comentários. Existe muitos códigos sem sequer uma linha de comentário. É meio dispendioso dar sequencia a programas. Pegar código desenvolvido por outra pessoa, estudar e continuar. Isto fica mais difícil a medida que as conhecidas boas práticas de programação não foram colocadas em práticas.
[4] Comentário enviado por texugo89 em 26/01/2008 - 01:32h
Parabéns pelo artigo!
Temos sempre que lembrar que trabalhamos em comunidade, mesmo que apenas nós trabalhemos no código um dia outros poderão atualiza-lo ou até mesmo nós!
É sempre bom lebrar dessas dicas!
[6] Comentário enviado por Teixeira em 27/01/2008 - 09:48h
Parabéns, albertguedes, não apenas pela natureza e conteúdo de seu artigo, mas também pela nobre iniciativa.
Trabalhar com manutenção de software no passado era algo "necessariamente" penoso, visto que os desenvolvedores procuravam propositadamente complicar o código, para dificultar seu entendimento por parte de terceiros, ou mesmo negligenciavam a importância de uma boa documentação.
Programadores "assembly" faziam um monte de desvios para cá e para lá e até mesmo encriptavam simples textos que deveriam ser impressos;
O pessoal do visual basic fazia formulários invisíveis, difíceis de rastrear, e por aí vai...
Documentação é algo preciosíssimo, mesmo para uso próprio.
Tenho programas em assembly, de minha autoria, e que não tenho certeza do que estão fazendo exatamente em determinados trechos, pois na época não os documentei. (Não trabalho com assembly há mais-ou-menos 20 anos).
Em meu antigo sistema de pessoal ( hoje seria "RH" ) existem tabelas que não sei mais onde ficam, pois foram profundamente modificadas ao longo dos anos (antigamente a contribuição ao INPS - hoje INSS - era de 8% fixos; não havia uma tabela, que teve de ser inserida "no tapa"), as bases de cálculo do IRF eram outras, etc.
Os remendos foram tantos que hoje até mesmo eu - o autor - desistiria facilmente de fazer qualquer manutenção.
É desnecessário dizer que esse sitema não roda mais, pois é da época dos mini-computadores ( que eram pequenos dinossauros que pesavam quase uma tonelada ).
Felizmente, depois de algum tempo, despertei para a necessidade de comentar TUDO o que o código se propunha a fazer.
E por falar em documentação e atualização, existe uma lenda(?) que diz respeito a um certo DISCO CARDOSO, que seria em nosso jargão de 20 anos atrás a mídia contendo a versão mais atual de um determinado programa. Dizem que havia um analista chamado Cardoso que, diante de muita confusão envolvendo versões de um mesmo software, onde um desenvolvedor fazia um remendo e chamava aquilo de versão 1.1 e outro fazia algo semelhante e lhe dava o nome de versão 1a, etc. , esse mesmo Cardoso determinou que todas as versões teriam que ser copiadas no SEU disco para poderem ser distribuídas, com o nome correto e definitivo da última versão, e com a documentação necessária.
Se a história é verdadeira não sei, mas era comum centralizarmos todo o trabalho da equipe em um disco comum, que chamávamos de DISCO CARDOSO...
Saudações a todos!
[7] Comentário enviado por removido em 27/01/2008 - 19:33h
Muito bom o propósito do artigo!
Porém tenho minhas críticas(construtivas) a serem feitas:
1. O cabeçalho contendo todas estas informações citadas prefiro que tenha um padrão como o utilizado na PHPDoc < http://pastebin.com/f1838ca98 >.
2. Já histórico do sistema tenho 100% de convecção que deve ficar em um repositório de arquivos, que depois de 1 ano de modificações constantes no sistema os scripts ficaram maiores que livros :P. Ou na pior das hipóteses em um arquivo chanchelog.`versao`.
[8] Comentário enviado por albertguedes em 27/01/2008 - 19:44h
Você tem razão Felipe, e na verdade a coisa é até mais complexa.
Mas é que neste artigo eu estou visando aqueles que estão começando a programar, então tentei fazer o modo mais funcional e pratico possivel, principalmente para aqueles que forem publicar aqui no VOL, que nao é exatamente um repositorio profissional.
Quanto ao cabeçalho do PHPdoc , fica como uma ótima alternativa, foi muito bom ter citado ele. Quem quiser usa-lo, tanto melhor.
Muito obrigado pela sua opinião.