Coloque ordem em seus programas

albertguedes

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.

[ Hits: 22.032 ]

Por: albert guedes em 25/01/2008 | Blog: https://teko.net.br

1 0

Denuncie Favoritos Indicar Impressora

A parte light

Então vamos as explicações:

Nome do programa

O nome do programa pode ser necessário, pois no caso de alguém mudar o nome do arquivo que contém a fonte, estando o nome do programa escrito no cabeçalho do código, este se torna a referência para identificá-lo.

Se outra pessoa tiver a mesma fonte e quiser comparar com a sua, ambos deverão verificar o nome do programa nas fontes, que é mais seguro, e não nos nomes dos arquivos. Aqui também deve ser dado uma pequena descrição do que o programa faz.

Versão

Essa dá para entender mais naturalmente devido ser corriqueiro todo mundo procurar a "versão mais nova de tal programa".

Realmente, colocar a versão pode ser uma medida do quão desenvolvido está seu programa, mas não quer dizer necessariamente o quão bom ele está, isso depende da habilidade do programador.

Por isso coloque a versão para as pessoas saberem que o programa foi melhorado e que há outros que estão obsoletos por falhas ou falta algum recurso que a nova versão possui.

Data da versão

"Oras bolas, se eu coloquei a versão atual, por que preciso colocar a data ?"
Tudo bem, seu programa está na versão 12343.5, mas foi feito em 01/2006, enquanto que a versão 12343.4 foi escrita em 06/1975.

O que você fez de melhoria no seu programa ou foi muito pouco, dado que sua melhoria foi do .4 para o .5, oi foi muita melhoria por você estar trabalhando nele há 21 anos. Por aí se vê, a versão pode indicar uma melhoria em relação a versão anterior, mas colocar a data indica o quanto você está está atualizado em relação ao mundo. Pode ter certeza, coloque a data da versão que os outros vão se sentir bem mais seguros.

Autor(es) e colaboradores

Todo pai tem responsabilidade pelo filho que bota no mundo, tanto na vida real quanto na metafórica, não podemos criar um programa e depois deixar ao léu.

Se alguma pessoa precisar dê uma explicação sobre o pimpolho, deve ser colocado o nome do criador ou criadores do programa, pelo menos alguém que entenda a maior parte do funcionamento.

Além do mais, esquecer de colocar os devidos créditos é perder a chance de arranjar um emprego ou pelo menos manter o seu, e ainda ganhar fama, afinal, o ego sempre grita quando as coisas vão bem - e se esconde feito gato pro banho quando vão mal.

A sim, coloque os colaboradores também. Não sejamos ingratos.

Contato com o(s) desenvolvedor(es)

Colocar o nome, ganhou fama e ainda assim quer se esconder dos fãs?
De jeito nenhum, coloque seu email, endereço telefone, celular, msn, qualquer coisa que permita as pessoas entrarem em contato com você.

Sem isso é a mesma coisa que dizer que o programa foi feito por fantasmas.

Página anterior Próxima página

Páginas do artigo

   1. Cabeçalho escolar
   2. A parte light
   3. A parte hard
   4. Exemplo em um código de C

Outros artigos deste autor

Santos Dumont - Pioneiro do Opensource no Brasil

Leve introdução às linguagens de programação

Escreva partituras no Linux

A arte do tetra-boot

Canal IRC do VOL - Participe você também!

Leitura recomendada

KeepAlive para conexão discada (ou não)

Alguns recursos do BASH para você utilizar em seus programas

Fazendo backup do seu MySQL com API do Dropbox

Convertendo TXT ou HTML em OGG

Linux com boot no Pendrive, com todas as facilidades: Smart-USB_Key-Mania, PLOP Boot Manager e outros métodos

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.

0 0

[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

0 0

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

0 0

[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

0 0

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

0 0

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

0 0

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

Está é minha opinião.

Abraco,

Felipe Cardoso Martins

0 0

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

0 0

[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

0 0

[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

0 0