Analisar TODOs do projeto

[abevieiramota]

Analisar os TODOs do projeto e, para cada TODO, tentar resolvê-lo. Caso não encontre uma solução confiável, manter o TODO e adicionar ao seu comentário qual a dificuldade encontrada.

[gbraz]

Sobre os comentários dos métodos em OperacoesEmAlunos.java. Claro que para uma classe com métodos pequenos e para nosso uso apenas, um comentário como aquele é desnecessário. Contudo eu os fiz pensando ser interessante ter essa documentação dizendo o que o método faz, recebe como parâmetro e retorna, pois o Eclipse mostra toda essa descrição quando passamos o mouse por cima do nome, o que eu acho muito útil quando uso bibliotecas dos outros. Então quando é interessante por esse tipo de comentário, Abelardo?

[abevieiramota]

http://blog.codinghorror.com/when-good-comments-go-bad/ http://blog.codinghorror.com/code-tells-you-how-comments-tell-you-why/ /\ ótimo blog para ler sobre coisas menos mainstream de programação :) > para se divertir

Sobre quando comentar: principalmente quando seu código vai ser utilizado externamente à equipe e possui uma interface bem definida. Se vai ser utilizado apenas internamente à equipe(e por equipe entenda o grupo de pessoas envolvidas com o código durante todo seu desenvolvimento), o ideal, ao meu ver, é minimizar a necessidade de comentários maximizando a legibilidade do código. Por legibilidade entenda quão fácil alguém estranho ao código consegue entender a intenção/comportamento daquele código, apenas olhando para ele. Interface bem definida entram as API's ou qualquer biblioteca desenvolvida com o intuito de serem utilizadas por uma gama de usuários maior que a equipe de desenvolvimento. Nesse caso, aí sim, há um valor em si na documentação, que seria o de cristalizar a intenção do código em um formato(linguagem natural) mais fácil de ser lido por alguém que tenha interesse apenas no comportamento, no que o código faz, e não no que ele faz E como ele faz.

Uma das boas práticas defendidas pelo movimento ágil é a documentação via testes: é uma documentação validável, que dá um feedback automático: no lugar de um texto estático, testes que digam qual comportamento é esperado do código e que, portanto, documentem o comportamento do código. Com isso em mente, faz sentido escrever com muito carinho testes: devem ser de fácil leitura! http://www.agilemodeling.com/essays/agileDocumentationBestPractices.htm#ExecutableSpecifications

[gbraz]

Obrigado pela explicação. =)

[abevieiramota]

Uhu, acabei com os TODOs