+3
Documentando o seu Código Eficazmente
Sou um programador mais antigo que a maioria dos visitantes desse site, com experiência de 15 anos como desenvolvedor e já ví de tudo por aí. O que mais me assusta nos jovens programadores de hoje é a forma com que documentam seu código. Resolvi escrever este artigo para explicar como e porquê fazer a documentação. Bom proveito e espero que tirem alguma coisa útil deste artigo.
O que é documentação?
Como nos ensinaram os mestres, documentação de um código, é nada mais do que papéis e notas que utilizaremos ao longo do desenvolvimento de nosso código. Sei que, a princípio, esta definição pode parecer que apenas estamos agregando tempo ao desenvolvimento do nosso código mas, como poderão ver a seguir, estamos sim é resumindo tempo em futuras correções e implementações que, fatalmente, ocorrerão.
Tenho visto que muita gente apenas comenta algumas linhas de seu código na hora de publicar uma dúvida ou pedir ajuda à algum especialista. Documentar seu código é bem mais do que isso. O primeiro passo da documentação, consiste em escrever o que se pretende com o código que está desenvolvendo. Escrever um bom fluxograma e um espelho da base de dados é fundamental para garantir que o que se está tentando fazer não perca seu “rumo”. Fluxogramas, e espelho de base de dados, o que vem a ser isso?
Fluxograma: Forma gráfica representativa da sequência informacional a ser seguida por seu código. Ficou difícil? Eu simplifico exemplificando com um fluxograma de uma página de login.
Eu traduzo - A página terá além de outros dados não sistêmicos, um formulário contendo dados a serem preenchidos na ordem: Usuário, Senha e um botão de submit que enviará os dados a outra rotina chamada autenticação.
Pode parecer ridículo que eu escreva uma coisa banal como esta mas, pense maior. Pense no seu sistema e tente fazer um fluxograma de rotinas mais complexas antes de começar a escrevê-las. Quando for efetivar (escrever o código), basta seguir o que está listado em seu fluxo que fica mais fácil. Outra coisa, enquanto se escreve este fluxograma, você já cerca diversos erros de precedência que ocorrem durante a escrita e podemos nos concentrar mais na “linguagem”. Ainda tem mais, quando se precisar fazer uma correção ou implementação no seu código (estou falando de erros estruturais e não de escrita), dê uma olhada antes em seu fluxo. Essa simples tarefa facilitará muito a sua vida.
Espelho de base de dados: É a formulação de seu banco de dados propriamente dita. De posse do seu fluxograma, você saberá quais dados está manipulando e, poderá colocar no papel como estes dados serão armazenados em seu sistema. Não estou falando da estrutura da base de dados mas da FORMA com que eles serão tratados (além da estrura). Veja um exemplo do fluxo acima:
Na formulação acima, coloco os dados que preciso em minha base de dados e relaciono como ela será utilizada em todo o meu sistema. Sei que CAMPO, TIPO e TAMANHO MÁXIMO você já tem em seu banco mas e o resto, para que serve?
TAMANHO MÍNIMO – Esta descrição prevê o tamanho mínimo a ser aceitado em suas funções que envolvam o campo. Neste caso, prevejo que um nome de usuário e sua senha nunca poderão ter menos do que 6 dígitos. Para login e senha isso é meio óbvio mas pense num banco de dados de produtos? Pode ser (e é) muito útil se ter esses dados em mãos.
FILTRO – O nome pode ser meio genêrico mas uso para prever que o campo usuário nunca poderá ser igual na minha base. Uso também para descrever que o campo TIPO conterá um numero e listo qual sua relação para mim no desenvolvimento do programa.
ESCOPO – Apesar de não ter utilizado neste exemplo, pense em um CPF. Seu escopo é 999.999.999-99 (onde os 9 significam números e os demais não estarão listados em minha base de dados. Outro exemplo (para vermos sua melhoria), um telefone poderia ter escopos diferentes durante o meu programa. Vejamos:
Se o “cliente” for do brasil, seu escopo será (99)_9999-9999
Se o cliente for internacional, seu escopo será (999_999)_9999-9999
RELAÇÃO – Quando trabalhamos com mais de um arquivo e um se relaciona com outro, usamos as chamadas CHAVES DE RELACIONAMENTO (tem bons artigos escritos aqui no site sobre o assunto. Liste aí sua chave para os child-relations (arquivos dependentes) especificando o arquivo e seu campo de relação.
Volto ao assunto, pense longe (em um sistema um pouquinho maior). Quando você chegar a linha de número 15000 do seu programa já tendo escrito 50 ou 100 rotinas diferentes, esta documentação será muito útil e abreviará seu tempo de “lembrança” dos dados criados lá na primeira rotina.
Agora, vamos falar um pouco da documentação que tenho visto por ai, as famosas “linhas comentadas”. Não ache que estou tirando o mérito delas com o que escreví antes mas, separe as coisas. Tudo o que disse antes se refere a ESTRUTURA e as linha comentadas vão afetar as rotinas.
Seja um pouco mais cauteloso e especifique em BOM PORTUGUÊS (ou seja lá na lingua que você está programando) o que você está POR FAZER e não o que acaba de fazer. Enquanto você comenta esta linha, tem mais tempo para pensar no que está por escrever, facilitando a sua vida e a de todos que por ventura você vier a pedir ajuda (ou dar sequência no seu trabalho). Separe as linhas de comentarios do resto do seu código par que elas fiquem fáceis de serem localizadas e comente a rotina que está por escrever.
Algumas boas formas de se fazer isso:
Quando você quiser achar esta parte do programa, fica fácil localizá-la no meio das cento e tantas linhas de cada rotina. Estas linhas comentadas não são intepretadas pelo PHP e não “roubam” processamento do seu servidor, então abuse delas (com coerência).
Não menos importante, comente as linhas MUITO importantes e variáveis com nome estranhos que você utilizar durante a programação. Exemplifico:
Bom, espero que tirem proveito disso e, finalizo com algumas observações que quem programa a mais tempo sabe:
- O tempo gasto agora para documentar será recuperado em dobro na correção
- Uma boa documentação triplica o valor de venda do seu sistema
- Sistemas são sempre melhorados, então, pense em você velho e chato tendo de lembrar o que fez quando criança e adivinhar o que tinha feito
- Linguagens sofrem updates constantes e sua documentação facilitará seu retrabalho.
Boa sorte a todos
O que é documentação?
Como nos ensinaram os mestres, documentação de um código, é nada mais do que papéis e notas que utilizaremos ao longo do desenvolvimento de nosso código. Sei que, a princípio, esta definição pode parecer que apenas estamos agregando tempo ao desenvolvimento do nosso código mas, como poderão ver a seguir, estamos sim é resumindo tempo em futuras correções e implementações que, fatalmente, ocorrerão.
Tenho visto que muita gente apenas comenta algumas linhas de seu código na hora de publicar uma dúvida ou pedir ajuda à algum especialista. Documentar seu código é bem mais do que isso. O primeiro passo da documentação, consiste em escrever o que se pretende com o código que está desenvolvendo. Escrever um bom fluxograma e um espelho da base de dados é fundamental para garantir que o que se está tentando fazer não perca seu “rumo”. Fluxogramas, e espelho de base de dados, o que vem a ser isso?
Fluxograma: Forma gráfica representativa da sequência informacional a ser seguida por seu código. Ficou difícil? Eu simplifico exemplificando com um fluxograma de uma página de login.
Eu traduzo - A página terá além de outros dados não sistêmicos, um formulário contendo dados a serem preenchidos na ordem: Usuário, Senha e um botão de submit que enviará os dados a outra rotina chamada autenticação.
Pode parecer ridículo que eu escreva uma coisa banal como esta mas, pense maior. Pense no seu sistema e tente fazer um fluxograma de rotinas mais complexas antes de começar a escrevê-las. Quando for efetivar (escrever o código), basta seguir o que está listado em seu fluxo que fica mais fácil. Outra coisa, enquanto se escreve este fluxograma, você já cerca diversos erros de precedência que ocorrem durante a escrita e podemos nos concentrar mais na “linguagem”. Ainda tem mais, quando se precisar fazer uma correção ou implementação no seu código (estou falando de erros estruturais e não de escrita), dê uma olhada antes em seu fluxo. Essa simples tarefa facilitará muito a sua vida.
Espelho de base de dados: É a formulação de seu banco de dados propriamente dita. De posse do seu fluxograma, você saberá quais dados está manipulando e, poderá colocar no papel como estes dados serão armazenados em seu sistema. Não estou falando da estrutura da base de dados mas da FORMA com que eles serão tratados (além da estrura). Veja um exemplo do fluxo acima:
Campo Tipo T. Min. T. Max. Filtro Escopo Relação
usuario char 6 15 único
senha char 6 15
tipo num 1 1 0 - Admin
1 - Cliente
2 - Fornec 0
Na formulação acima, coloco os dados que preciso em minha base de dados e relaciono como ela será utilizada em todo o meu sistema. Sei que CAMPO, TIPO e TAMANHO MÁXIMO você já tem em seu banco mas e o resto, para que serve?
TAMANHO MÍNIMO – Esta descrição prevê o tamanho mínimo a ser aceitado em suas funções que envolvam o campo. Neste caso, prevejo que um nome de usuário e sua senha nunca poderão ter menos do que 6 dígitos. Para login e senha isso é meio óbvio mas pense num banco de dados de produtos? Pode ser (e é) muito útil se ter esses dados em mãos.
FILTRO – O nome pode ser meio genêrico mas uso para prever que o campo usuário nunca poderá ser igual na minha base. Uso também para descrever que o campo TIPO conterá um numero e listo qual sua relação para mim no desenvolvimento do programa.
ESCOPO – Apesar de não ter utilizado neste exemplo, pense em um CPF. Seu escopo é 999.999.999-99 (onde os 9 significam números e os demais não estarão listados em minha base de dados. Outro exemplo (para vermos sua melhoria), um telefone poderia ter escopos diferentes durante o meu programa. Vejamos:
Se o “cliente” for do brasil, seu escopo será (99)_9999-9999
Se o cliente for internacional, seu escopo será (999_999)_9999-9999
RELAÇÃO – Quando trabalhamos com mais de um arquivo e um se relaciona com outro, usamos as chamadas CHAVES DE RELACIONAMENTO (tem bons artigos escritos aqui no site sobre o assunto. Liste aí sua chave para os child-relations (arquivos dependentes) especificando o arquivo e seu campo de relação.
Volto ao assunto, pense longe (em um sistema um pouquinho maior). Quando você chegar a linha de número 15000 do seu programa já tendo escrito 50 ou 100 rotinas diferentes, esta documentação será muito útil e abreviará seu tempo de “lembrança” dos dados criados lá na primeira rotina.
Agora, vamos falar um pouco da documentação que tenho visto por ai, as famosas “linhas comentadas”. Não ache que estou tirando o mérito delas com o que escreví antes mas, separe as coisas. Tudo o que disse antes se refere a ESTRUTURA e as linha comentadas vão afetar as rotinas.
Seja um pouco mais cauteloso e especifique em BOM PORTUGUÊS (ou seja lá na lingua que você está programando) o que você está POR FAZER e não o que acaba de fazer. Enquanto você comenta esta linha, tem mais tempo para pensar no que está por escrever, facilitando a sua vida e a de todos que por ventura você vier a pedir ajuda (ou dar sequência no seu trabalho). Separe as linhas de comentarios do resto do seu código par que elas fiquem fáceis de serem localizadas e comente a rotina que está por escrever.
Algumas boas formas de se fazer isso:
Seu código Seu código /* Faz a conexão com o banco de dados */ Seu código Seu código Ou ainda: Seu código Seu código //----------------------------------------------------------------------------- // Faz a conexão com o banco de dados //----------------------------------------------------------------------------- Seu código Seu código
Quando você quiser achar esta parte do programa, fica fácil localizá-la no meio das cento e tantas linhas de cada rotina. Estas linhas comentadas não são intepretadas pelo PHP e não “roubam” processamento do seu servidor, então abuse delas (com coerência).
Não menos importante, comente as linhas MUITO importantes e variáveis com nome estranhos que você utilizar durante a programação. Exemplifico:
echo $o_c_usuario; // imprime o codigo velho do usuario
Bom, espero que tirem proveito disso e, finalizo com algumas observações que quem programa a mais tempo sabe:
- O tempo gasto agora para documentar será recuperado em dobro na correção
- Uma boa documentação triplica o valor de venda do seu sistema
- Sistemas são sempre melhorados, então, pense em você velho e chato tendo de lembrar o que fez quando criança e adivinhar o que tinha feito
- Linguagens sofrem updates constantes e sua documentação facilitará seu retrabalho.
Boa sorte a todos
Comentários:
Mostrando 1 - 9 de 9 comentários
Já há algum tempo, eu vinha notando que quanto mais eu comentava (explicando para mim mesmo) meus coódigos, menos erros eles apresentavam e se surgissem, mais rápido eu os corrigia... Agora com essas idéias, espero melhorar ainda mais! Obrigado!
28/03/2004 5:08pm
(~20 anos atrás)
Eu não conhecia o coding standarts da PEAR.. realmente nota 10. Mas, não é especificamente da PEAR, mas sim, do phpDocumentor.
http://phpdoc.org/docs/HTMLSmartyConverter/default/phpDocumentor/tutorial_phpDocumentor.pkg.html
A partir de agora todos meus códigos vão seguir esse padrão, ainda mais que seguindo o mesmo, o código é auto documentado pelo phpDocumentor.
http://phpdocu.sourceforge.net/
Vale a pena ver.
http://phpdoc.org/docs/HTMLSmartyConverter/default/phpDocumentor/tutorial_phpDocumentor.pkg.html
A partir de agora todos meus códigos vão seguir esse padrão, ainda mais que seguindo o mesmo, o código é auto documentado pelo phpDocumentor.
http://phpdocu.sourceforge.net/
Vale a pena ver.
23/01/2004 2:32pm
(~21 anos atrás)
Com todo prazer.
Apenas te peço para manter o crédito (se for possível). Uma outra coisa que você pode colocar, como motivo de ênfase ao uso de documentação é que, minha empresa (entre milhares de outras que trabalho), não contratam ou aceitam serviços sem sua documentação no formato ANSI.
Estou concentrando meus esforços de escrita de artigos nesta parte de referências globais para novos programadores e, em breve, estarei disponibilizando mais um que pode te ser útil. Qualquer cois, faça contato aqui ou pelo e-mail:
jporto@inforage.com.br
Um Abraço
Apenas te peço para manter o crédito (se for possível). Uma outra coisa que você pode colocar, como motivo de ênfase ao uso de documentação é que, minha empresa (entre milhares de outras que trabalho), não contratam ou aceitam serviços sem sua documentação no formato ANSI.
Estou concentrando meus esforços de escrita de artigos nesta parte de referências globais para novos programadores e, em breve, estarei disponibilizando mais um que pode te ser útil. Qualquer cois, faça contato aqui ou pelo e-mail:
jporto@inforage.com.br
Um Abraço
10/02/2003 6:16am
(~22 anos atrás)
Valeu e anotado.
vou começar a fazer a perte sobre "economia" onde irei englobar funções, classes e modos de se fazer um sistema mais limpo.
Também vejo que muita gente usa, mais não sabe porque. Valeu a idéia e obrigado pelo comentário.
Jayr
vou começar a fazer a perte sobre "economia" onde irei englobar funções, classes e modos de se fazer um sistema mais limpo.
Também vejo que muita gente usa, mais não sabe porque. Valeu a idéia e obrigado pelo comentário.
Jayr
01/02/2003 9:21am
(~22 anos atrás)
Desculpe Rafael mas, não entendi.
Não começa porque? Sei que isso parece complicar, numa primeira olhada mais, a inteção do artigo é mostrar que, documentando, seu trabalho fica mais fácil e nao mais complicado.
Veja bem, Principalmente quem esta começão, vai precisar de ajuda. Se seu código estiver bem documentado, vai ficar muito mais fácil de qualquer pessoa dar um help pois vai entender o que você esta querendo.
Não começa porque? Sei que isso parece complicar, numa primeira olhada mais, a inteção do artigo é mostrar que, documentando, seu trabalho fica mais fácil e nao mais complicado.
Veja bem, Principalmente quem esta começão, vai precisar de ajuda. Se seu código estiver bem documentado, vai ficar muito mais fácil de qualquer pessoa dar um help pois vai entender o que você esta querendo.
26/01/2003 10:51am
(~22 anos atrás)
Bem lembrado. Não incluí esta parte no artigo pois vai além da documentação. Seria interssante passar esta idéia de como escrever nosso códigos com "legibilidade" que muitos acham que consomem processamento e, na verdade, cria um ambiente bem mais "entendivel".
Escreví este artigo pois fico cançado em tentar ajudar aos outros e receber aqueles MONSTROS que ninguem consegue entender e localizar nada.
Obrigado pelos comentários (isso insentiva a novos artigos).
Escreví este artigo pois fico cançado em tentar ajudar aos outros e receber aqueles MONSTROS que ninguem consegue entender e localizar nada.
Obrigado pelos comentários (isso insentiva a novos artigos).
22/01/2003 11:13am
(~22 anos atrás)
outro ponto importante na programação que facilita bastente a compreensão do código é o espaçamento entre operações e funções como usar:
if ($numero1 == $numero2)
{
echo "igual";
}
usando Tab para separar bem as chaves, ficam mais chamativas do que entrar com 3/4 espaços
if ($numero1 == $numero2)
{
echo "igual";
}
usando Tab para separar bem as chaves, ficam mais chamativas do que entrar com 3/4 espaços
20/01/2003 11:23am
(~22 anos atrás)
Cara teu artigo só reforça mais ainda que não se pode existir gênios na programação mas sim pessoas que façam seus códigos para que o próximo que venha a utiliza-ló saiba qual foi a intenção e o que a aquele código pode promover e apontar uma saída é melhor desenvolver o algoritmo no papel do que perde tempo no pc corrigindo pequenos erros e sempre modificando o código.. isso faz com que se perca mais tempo e torna o trabalho mais dificil.. e ainda se perde a lógica..
Parabéns
[]'s
Diego
Parabéns
[]'s
Diego
18/01/2003 7:32pm
(~22 anos atrás)
Muito bom, Jayr. Parabens.
Sou um adepto incondicional da documentacao. Normalmente procuro documentar tudo o que faco, nao só no programa, como fazer um documento (redundancia) a parte, especificando tudo o que fiz, inclusive quando tenho que configurar alguma coisa "rara".
E, realmente, isto ajuda muito, e compensa, com folga, o chamado "tempo perdido" da documentacao.
Realmente, vale a pena. Parabens de novo.
Sou um adepto incondicional da documentacao. Normalmente procuro documentar tudo o que faco, nao só no programa, como fazer um documento (redundancia) a parte, especificando tudo o que fiz, inclusive quando tenho que configurar alguma coisa "rara".
E, realmente, isto ajuda muito, e compensa, com folga, o chamado "tempo perdido" da documentacao.
Realmente, vale a pena. Parabens de novo.
18/01/2003 8:58am
(~22 anos atrás)