Até um tempo atrás eu acreditava que, por meu código estar
fácil de ser interpretado, eu não precisava comenta-lo, pois
perderia um tempo para tal. Depois de um tempo fui percebendo ao
utilizar alguns métodos antigos, que era um pouco difícil a
manutenção deles, além de ser um grande problema o entendimento
por outros programadores. Como eu evitaria esse problema? A resposta
é muita simples, só comentar.
Mas porque devo fazer uma boa
documentação? O que isso influenciara no meu projeto? E como eu sei
se meu comentário esta bom, ruim, insuficiente?
Bom veremos isto abaixo
Primeiro, O que seria documentação?
Documentação descreve cada
parte do
código-fonte, uma função, uma classe, um trecho ou
módulo. Podemos dizer que a documentação consiste
em um conjunto
de manuais gerais e técnicos, podendo ser organizado em forma de
textos e comentários,
utilizando ferramentas do tipo dicionários,
diagramas e fluxo gramas, gráficos, desenhos, dentre outros.
Mas, por que documentar? O que isso irá me trazer de bom
As razões
básicas para
documentar um código é auxiliar a comunicação
durante o
desenvolvimento do software e auxiliar o
entendimento nas atividades
de manutenção e
atualização quando se fizerem necessárias.
Para você ter uma idéia mais de
50% do trabalho de evolução de um software é
dedicado ao
entendimento do programa e a tarefa mais
difícil da manutenção é
o entendimento da estrutura do
sistema. Por isso, o desenvolvedor
deve encontrar um
ponto de equilíbrio na quantidade de
documentação
gerada e encontrar as ferramentas que facilitarão o
entendimento da documentação, tanto para o
administrador quanto
para o futuro usuário do
software.
Alguns problemas são apontados
pela falta de
documentação adequada. Dentre eles podemos citar as
dificuldades para a atualização e manutenção,
dificuldades de
acesso do usuário e alto custo para o
software.
Exemplos:
Código mal estruturado
Com este código você não entende o que é a classe, o que ela faz, quais são os métodos, quais são os argumentos dos métodos, E com certeza você perderá tanto tempo tentando entende-la, que compensava mais se recriar ela.
public class classe2 {
public void pessoa (String
var1, int var2){
Pessoa a = new Pessoa;
a.setName(var1);
int t = calcula(var2, 2012);
a.setIdade(t);
}
private int calcula(int var1,
int var2){
int var3 = var1 – var2;
return var3;
}
}
Código bem estruturado
Só pelos nomes de classe, métodos e argumentos, você consegue identifica o que a classe faz sem muita
dificuldade
public class GerenciaPessoa {
public void novaPessoa(String
nome, int anoNascimento){
Pessoa pessoa = new Pessoa;
pessoa.setName(nome);
int idade =
calculaIdade(anoNascimento, 2012);
pessoa.setIdade(idade);
}
private int calculaIdade(int
anoNascimento, int anoAtual){
int idade = anoAtual –
anoNascimento;
return idade;
}
}Contém comentário, mas e ae, o que ele faz? Seria isso uma data de criação? É fica um pouco difícil.
// 05 – 12 - 2012
private boolean validaAltura(var
1, var 2){
int
var3;
if(var1
> var2){
var3
= (var2-var1)/2}else{var3
= (var2-var1)*5}if(var3
> 1){return
true;}else{ return
false;}
}
Ok, você comentou o código, mas de um forma que esta na cara que aquilo (classe, métodos, função) já fazia. Por exemplo var2 – var1, eu sei que subtrai, eu estou lendo, você não precisa comentar isto, outra é a classe, você se reescreveu o nome dela, ainda não explica o que ela faz.
// valida altura
private boolean validaAltura(var
1, var 2){
int
var3;
if(var1
> var2){
var3
= (var2-var1)/2 // subtrai var2 por var1 e divide por 2}else{var3
= (var2-var1)*5 // subtrai var2 por var1 e multiplica 5} if(var3
> 10){ // se var3 e maior que 10return
true;}else{return
false;}
}
Neste caso a descrição do método faz você conseguir entender o que o ele e as funções fazem
/*
* Valida a altura que ira ser
preciso para a definição do Predio, segundo o requisito 2
* param1 var1 – diâmetro do
predio
* param2 var2 – comprimento
da rua em relação ao predio
* return true, se a distancia
está ok
*/
private boolean validaAltura(var
1, var 2){
int
var3;
//
verfica se o var2 e maior que o var1, para calcular a densidade a ser
usada)
if(var1
> var2){
var3
= (var2-var1)/2 }else{ var3
= (var2-var1)*5 } //
caso a altura ultrapasse ao valor definido 10, então retornará true if
(var3 > 10){ return
true; }else{ return
false;}
}
Conclusão
Só pra concluir então, se você for
fazer um software, não deixe de fazer uma boa documentação, está
é a melhor arma para evitar futuras complicações
Até a próxima ae galera,
lembrando que qualquer dúvida,
reclamação ou sugestão, entrar em contato em.
Flws.
Referencia
http://www.leandrogarcia.com/blog/a-importancia-de-comentar-seu-codigo-e-comentar-direito/
http://www.periodicos.letras.ufmg.br/index.php/textolivre/article/view/24
Nenhum comentário:
Postar um comentário