Bom pessoal, hoje vou falar um pouco sobre as boas práticas
na hora de comentar e documentar um código no ambiente corporativo.
Primeiramente gostaria de deixar bem claro o fato de que o mundo acadêmico e o
mundo corporativo têm expectativas e realidades muito diferentes, portanto os
padrões que foram aprendidos dentro de uma universidade, ou através de livros,
nem sempre são bem vistos no mundo dos negócios.
Por exemplo, os códigos fontes que são postados aqui nesse
blog possuem uma quantidade excessiva e desnecessária de comentários, do ponto
de vista empresarial, e o porquê disso é o que iremos abordar abaixo. Porém,
esse excesso aqui cometido é proposital para que possamos ser o mais didático
possível e para que qualquer um possa entender o funcionamento dos nossos
códigos, aí você me pergunta, “Mas esse não é o objetivo dos comentários em
qualquer situação? Inclusive no ambiente corporativo. ”, para responder essa
pergunta vamos levar em conta os seguintes pontos:
1) Comentários não são legendas
// Passa por todas as bananas no cacho
foreach(banana b no cacho) {
monkey.eat(b); //Faz o macaco comer a banana
}
Você não precisa explicitar o que faz cada linha do seu
código, após um período não tão grande de tempo, qualquer programador poderá
ler linhas de códigos quase tão bem quanto entende a sua linguagem nativa. A exceção
para esses casos são linguagens de programação muito próximas a linguagem de
máquina, como por exemplo Assembly.
2) Comentários não são projetos de arte
Esta é uma péssima prática de programação muito disseminada por exemplos em livros e copyright de códigos open source, pois são formas de chamar a atenção do leitor. Como por exemplo:
/*
_ _ _ _ _ _ _ _ _ _ _ _
(c).-.(c) (c).-.(c) (c).-.(c) (c).-.(c) (c).-.(c) (c).-.(c)
/ ._. \ / ._. \ / ._. \ / ._. \ / ._. \ / ._. \
__\( Y )/__ __\( Y )/__ __\( Y )/__ __\( Y )/__ __\( Y )/__ __\( Y )/__
(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)
|| M || || O || || N || || K || || E || || Y ||
_.' `-' '._ _.' `-' '._ _.' `-' '._ _.' `-' '._ _.' `-' '._ _.' `-' '._
(.-./`-'\.-.)(.-./`-'\.-.)(.-./`-'\.-.)(.-./`-'\.-.)(.-./`-'\.-.)(.-./`-'\.-.)
`-' `-' `-' `-' `-' `-' `-' `-' `-' `-' `-' `-'
-It's Monkey Business Time! (Version 1.5)
*/
Você pode achar que nunca faria algo parecido, mas repare
que o código abaixo não é muito diferente, apenas mais trabalhados.
+------------------------------------------------------------+ | Module Name: classMonkey | | Module Purpose: emulate a monkey | | Inputs: Bananas | | Outputs: Grunts | | Throws: Poop | +------------------------------------------------------------+
Programadores adoram
enfeitar os seus comentários, como no exemplo acima, quando estão cansados e
precisam parar de pensar no problema que estão tentando resolver. O problema
com essa prática é que ela gera uma perda de horas para a manutenção desses
comentários para qualquer um que vá trabalhar com eles. Mesmo programadores que
não gostam disso, perdem tempo na manutenção dos layouts, pois se incomodam com
a inconsistência ou a quebra do layout. Você pode até achar que isso não é
verdade, mas aposto que a quebra de layout na coluna da direta está te
incomodando.
3) Cabeçalhos: Incomodo ou Ameaça?
Cabeçalhos tanto de classes como de métodos são ruins pois eles abrem uma brecha para que se dê nomes ruins aos métodos, pois são uma desculpa para não colocar nomes que representem as funcionalidades. Além disso, esses códigos nunca são atualizados o que pode levar ao leitor a uma ideia errada do real funcionamento do código, caso alguém leia esse comentário, o que raramente ocorre.
Óbvio que existem exceções
para esse caso, uma delas é o Java que disponibiliza o JavaDoc que possibilita
a criação de cabeçalhos, especialmente formatados, que disponibilizam essa
documentação no momento que o desenvolvedor usa o auto complete. Além de ser
possível gerar uma documentação completa do sistema através de ferramentas que
extraem esses comentários.
4) Comentários não são controles de código
// method name: pityTheFoo (Incluido para aumentar a redundancia)
// created: Feb 18, 2009 11:33PM
// Author: Bob
// Revisions: Sue (2/19/2009) - Lengthened monkey's arms
// Bob (2/20/2009) - Solved drooling issue
void pityTheFoo() {
...
}
Hoje não existem empresas que desenvolvam um sistema sem o
uso de softwares de controle de versão e esse software é perfeitamente capaz de
armazenar e atualizar as informações que são colocadas em comentários como o
mostrado acima, isso sem que seja preciso sujar o código e obrigar os outros
desenvolvedores a gastar seu tempo para atualiza-los. Obviamente, os
desenvolvedores que gostam desse tipo de comentário geralmente são aqueles que
não colocam nenhuma informação, ou informações imprecisas, nos commits de
código.
5) Comentários são sinais de códigos ruins
A quantidade excessiva de comentários são geralmente um
indicativo que o código precisa passar por um processo de refactor. Sempre que
você achar que seu código precisa de comentários para ser entendido, você deve
se fazer a seguinte pergunta "Como posso refatorar meu código para que seu
objetivo fique claro?".
Conclusão:
Com esses 5 pontos podemos responder a pergunta, “Mas esse
não é o objetivo dos comentários em qualquer situação? Inclusive no ambiente corporativo.
”, códigos quando utilizados corretamente podem e são muito uteis, mas devemos
ter cuidado com excessos ou comentários desnecessários pois isso pode gerar um
gasto de tempo de outros programadores para manter atualizados e com o formato
correto, os nossos comentários. Segue abaixo algumas dicas de como podemos
evitar o uso de comentários desnecessários:
1) Sempre prefira nomes significativos a comentários
// Before // Calculate monkey's arm length // using its height and the magic monkey arm ratio double length = h * 1.845; //magic numbers are EVIL! // After - No comment required double armLength = height * MONKEY_ARM_HEIGHT_RATIO;
2) Utilize entradas e saídas tipadas para os seus métodos
// Before
// input parameter monkeysToFeed:
// DataSet with one table containing two columns
// MonkeyID (int) the monkey to feed
// MonkeyDiet (string) that monkey's diet
void feedMonkeys(DataSet monkeysToFeed) {
}
// After: No comment required
void feedMonkeys(Monkeys monkeysToFeed) {
}
3) Extraia o trecho que necessita de comentários para outro método
// Before
// Begin: flip the "hairy" bit on monkeys
foreach(monkey m in theseMonkeys) {
// 5-6 steps to flip bit.
}
// End: flip the "hairy" bit on monkeys
// After No comment required
flipHairyBit(theseMonkeys);
4) Evite um encadeamento grande de estruturas de repetição ou decisão
} // ... if see evil
} // ... while monkey do.
} // ... if monkey see.
} // ... class monkey
} // ... namespace primate
Espero com esse artigo ter ajuda programadores novos e
veteranos a produzirem códigos melhores e principalmente a saber diferenciar o
estilo de programação que usamos ao criar tutoriais, entregar trabalhos na
faculdade, ou fazermos códigos para nós mesmos, do estilo que deve ser usado no
ambiente corporativo.
Nenhum comentário :
Postar um comentário