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

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

1 0

Denuncie Favoritos Indicar Impressora

Exemplo em um código de C

Aqui vou colocar um exemplo de um código fonte em C, "nosso hello.c" tão conhecido. Vou colocar umas firulas para melhorar a coisa.

// hello.c - Programa que imprime na tela a frase "Hello !"

// Versão 0.3

// Data da versão: 27/12/2007

// Autor: Albert R. C. Guedes
// Colaboradores: Só eu mesmo.

// Contatos:
//       Email: arcguede@gmail.com
//       MSN: albertguedes@hotmail.com
//       Pagina web: http://socrates.if.usp.br/~arguede

// Últimas atualizações:
// Versão 0.2: Foi colocado enfeites em volta da frase "Hello !"
// Versão 0.1: Não foi feito nada, era a primeira versão.

// Dependências:
//     bibliotecas: stdio.h

// Inicio do programa.

main(){

// Aqui é imprimido a frase "Hello !" em volta de
// sinais "=".
   printf("\n==========\n");
   printf("\n===Hello !===\n");
   printf("\n==========\n");

// Imprime a frase quando termina o programa.
    printf("Fim !\n");

}

Posfácio

Tentar manter a continuidade de um programa é muito difícil, principalmente quando existem projetos grandes, e estes então são um inferno se não forem bem organizados.

Espero que isso ajude aos programadores vindouros a criarem seus códigos de modo mais profissional e mais clara possível. Assim não só ajudarão aos outros que o acompanham, como a si mesmos.

Boa programação pessoal.

Página anterior

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

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

Conectando Ajato com Linux

Escreva partituras no Linux

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

Leitura recomendada

Colocado o "Motion" na inicialização do Ubuntu 7.04

Configurando OpenSSH no Windows Server 2003 para autenticação por chave (sem senha)

Como Configurar seu Lucent Winmodem

Ajustando a hora do micro com extrema precisão

Redundância de links - Mon + Shell Script

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