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.

Eis a lista destas coisas básicas:

• Nome do programa
• Versão
• Data em que foi terminada ou lançada a versão
• Autor(es) do programa e colaboradores
• Contato com o desenvolvedor(es)
• Histórico de desenvolvimento
• Dependências do programa
• Comentários

[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.

Parabéns pelo artigo.

[2] Comentário enviado por f_Candido em 25/01/2008 - 12:09h:

Excelente artigo. Tanto para os Novatos, quanto para os que já programam a algum tempo.

Parabéns

Abraços

[3] Comentário enviado por fabioarnoni em 25/01/2008 - 22:03h:

Ótimo artigo!!! Estou aprendendo C++ aqui na Faculdade e isso é importantíssimo na hora de fazer um programa, vou passar pra galera aqui falouu!!!

[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!

[]'s

[5] Comentário enviado por GilsonDeElt em 26/01/2008 - 15:55h:

Parabéns pelo artigo!

Já tá nos favoritos!

Tô aprendendo a programar, e isso vai me ser muito bom
vlw!

[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 macafe 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`.

Está é minha opinião.

Abraco,

Felipe Cardoso Martins

[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.

[9] Comentário enviado por fdmarp em 17/03/2009 - 19:39h:

Coisas simples, mas que muita gente esquece e que fazem toda a diferença, principalmente se é você que vai dar manutenção no programa ou script. Vaelu

[10] Comentário enviado por vinicios.barros em 17/03/2010 - 20:22h:

# por vinicios barros vinigrath@gmail.com
# eu uso esse script simples pra instalar e atualizar o ubuntu
# depois que faço uma nova instalação do SO
# ficadica! pra quem quiser usar ou modificar
# aqui nao tem o java nem o flash mas quem quiser adiciona
#
echo
echo irei efetuar atualizacoes | cowsay
echo -e "{COMENTARIO}33[01;33;40m EXECUTANDO COMANDO: sudo apt-get update {COMENTARIO}33[0m"
sudo apt-get update
echo
echo -e "{COMENTARIO}33[01;33;40mEXECUTANDO COMANDO: sudo apt-get dist-upgrade {COMENTARIO}33[0m"
sudo apt-get -y dist-upgrade
echo
echo -e "{COMENTARIO}33[01;33;40mEXECUTANDO COMANDO: sudo apt-get autoremove{COMENTARIO}33[0m"
sudo apt-get autoremove
echo
echo -e "{COMENTARIO}33[01;33;40mEXECUTANDO COMANDO: sudo apt-get clean{COMENTARIO}33[0m"
sudo apt-get clean
echo
echo sistema atualizado | cowsay -f tux
echo
echo
echo irei instalar alguns softwares | cowsay -f tux
echo -e "{COMENTARIO}33[01;33;40m Alguns programas serao instalados APERTE ENTER PARA CONTINUAR! ou CTRL C para sair"
read var
echo -e "{COMENTARIO}33[01;33;40m EXECUTANDO COMANDO: sudo apt-get -y install geany {COMENTARIO}33[0m"
sudo apt-get -y install geany
echo
echo -e "{COMENTARIO}33[01;33;40mEXECUTANDO COMANDO: sudo apt-get -y install sl {COMENTARIO}33[0m"
sudo apt-get -y install sl
echo
echo -e "{COMENTARIO}33[01;33;40mEXECUTANDO COMANDO: sudo apt-get install cowsay {COMENTARIO}33[0m"
sudo apt-get -y install cowsay
echo
echo -e "{COMENTARIO}33[01;33;40mEXECUTANDO COMANDO: sudo apt-get install kate {COMENTARIO}33[0m"
sudo apt-get -y install kate
echo
echo -e "{COMENTARIO}33[01;33;40mEXECUTANDO COMANDO: sudo apt-get install konsole {COMENTARIO}33[0m"
sudo apt-get -y install konsole
echo
echo -e "{COMENTARIO}33[01;33;40mEXECUTANDO COMANDO: sudo apt-get install audacious {COMENTARIO}33[0m"
sudo apt-get -y install audacious
echo
echo -e "{COMENTARIO}33[01;33;40mEXECUTANDO COMANDO: sudo apt-get install SSH {COMENTARIO}33[0m"
sudo apt-get -y install openssh-server
echo
echo -e "{COMENTARIO}33[01;33;40mEXECUTANDO COMANDO: sudo apt-get install aMSN {COMENTARIO}33[0m"
sudo apt-get -y install amsn
echo
echo -e "{COMENTARIO}33[01;33;40m EXECUTANDO COMANDO: sudo apt-get install g++ {COMENTARIO}33[0m"
sudo apt-get -y install g++
echo
echo -e "{COMENTARIO}33[01;33;40m EXECUTANDO COMANDO: sudo apt get install Lua5.1 {COMENTARIO}33[0m"
sudo apt-get -y install lua5.1
echo
echo -e "{COMENTARIO}33[01;33;40m EXECUTANDO COMANDO: sudo apt get install konqueror {COMENTARIO}33[0m"
sudo apt-get -y install konqueror
echo
echo -e "{COMENTARIO}33[01;33;40m EXECUTANDO COMANDO: sudo apt get install k3b {COMENTARIO}33[0m"
sudo apt-get -y install k3b
echo
echo -e "{COMENTARIO}33[01;33;40m EXECUTANDO COMANDO: sudo apt get install wine {COMENTARIO}33[0m"
sudo apt-get -y install wine
echo
echo -e "{COMENTARIO}33[01;33;40m EXECUTANDO COMANDO: sudo apt get install vlc media {COMENTARIO}33[0m"
sudo apt-get -y install vlc
echo
echo -e "{COMENTARIO}33[01;33;40m EXECUTANDO COMANDO: sudo apt get install Geany {COMENTARIO}33[0m"
sudo apt-get -y install geany
echo
echo -e "{COMENTARIO}33[01;33;40m EXECUTANDO COMANDO: sudo apt get install RapidSVN {COMENTARIO}33[0m"
sudo apt-get -y install rapidsvn
echo
echo -e "{COMENTARIO}33[01;33;40m EXECUTANDO COMANDO: sudo apt get install audacious {COMENTARIO}33[0m"
sudo apt-get -y install audacious
echo
echo -e "{COMENTARIO}33[01;33;40m EXECUTANDO COMANDO: sudo apt get install trafshow {COMENTARIO}33[0m"
sudo apt-get -y install trafshow
echo
echo irei efetuar atualizacoes novamente | cowsay
echo -e "{COMENTARIO}33[01;33;40m EXECUTANDO COMANDO: sudo apt-get update {COMENTARIO}33[0m"
sudo apt-get update
echo
echo -e "{COMENTARIO}33[01;33;40mEXECUTANDO COMANDO: sudo apt-get dist-upgrade {COMENTARIO}33[0m"
sudo apt-get -y dist-upgrade
echo
echo -e "{COMENTARIO}33[01;33;40mEXECUTANDO COMANDO: sudo apt-get autoremove{COMENTARIO}33[0m"
sudo apt-get autoremove
echo
echo -e "{COMENTARIO}33[01;33;40mEXECUTANDO COMANDO: sudo apt-get clean{COMENTARIO}33[0m"
sudo apt-get clean
echo
echo sistema atualizado | cowsay
echo
echo
echo My job is over, enjoy! | cowsay -f tux