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.373 ]

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

1 0

Denuncie Favoritos Indicar Impressora

A parte hard

Aqui se coloca as informações mais detalhadas do programa:

Histórico de desenvolvimento

O histórico são as melhorias gradativas que você coloca no programa.

Você acrescentou uma função nova na versão 3.2, um botão a mais na versão 4.5, tudo isso pode ser colocado no histórico, serve para um desenvolvedor que ler seu código, caso queira usar uma versão do programa que não tenha certa parte do código que ele não usa, ou para criar uma só dele ou que não precise para deixar o programa enxuto, o histórico diz mais ou menos onde ele deve procurar.

Dependências do programa

Se seu programa usa bibliotecas que não são padrões no sistema, ou depende de programas que você sabe que nem todo mundo instala, coloque estas dependências e torne o trabalho dos desenvolvedores que acompanham seu programa menos sofrível.

Comentários

Essa é a parte mais cara da história. COMENTEM SEMPRE SEU CÓDIGO.

Sempre explique o que um certo bloco ou linha de código faz, as que são muito simples de entender pode passar, mas até mesmo uma linha pode ser difícil pra alguém que está lendo o código compreender "por que aquela variável apareceu de repente e tem o mesmo valor daquela que não foi usada ainda?".

Linguagem de programação é outra língua - pra enfatizar a coisa - portanto têm que ter uma fácil tradução, senão demora demais as pessoas entenderem o algoritmo, e mesmo o próprio autor pode se confundir após um tempo afastado do projeto e verificar que não lembra patavinas do que ele queria fazer naquela parte do código.

Experiência própria de quem vos escreve.

E um programa publicado aqui no VOL é duas vezes mais necessário, pois muita gente está aprendendo uma linguagem e cada programa publicado serve como um aprendizado, temos o dever didático de comentar o que publicamos, não queremos que o pessoal aprenda errado não é mesmo?

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

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

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

Conectando Ajato com Linux

A arte do tetra-boot

Santos Dumont - Pioneiro do Opensource no Brasil

Leitura recomendada

Processos

Script de backup full + diferencial + compactador + restauração

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

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

Como configurar o servidor de correio eletrônico Postfix

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