Bom código é código comentado, não é mesmo? Nem sempre. Saiba nesta palestra quando se está ajudando ou apenas "usando um desodorante".

1. // não comente seu código ...
Márcio Torres

2. Qualidade
Funcionalidade
Confiabilidade
Usabilidade
Eficiência
Manutenibilidade
Portabilidade

3. Manutenibilidade
Analisibilidade
Modificabilidade
Estabilidade
Conformidade
Testabilidade

4. Manutenibilidade
Facilidade e simplicidade de alterar um
programa já existente, seja para corrigir um bug,
ajustar ou introduzir funcionalidades.

5. Economia da Manutenibilidade
$custo_manter = $custo_entender
+ $custo_alterar + $custo_testar
+ $custo_implantar

6. Economia da Manutenibilidade
$custo_manter = $custo_entender
+ $custo_alterar + $custo_testar
+ $custo_implantar

7. Economia da Inteligibilidade
Difícil de Entender Fácil de Entender
< tempo implementação
> tempo cada alteração
> tempo implementação
< tempo cada alteração

8. Tornando o código inteligível,
adicionando comentários

9. O que me disseram
sobre comentar o código
● Código bom é comentado
● Tu deves adicionar comentários para explicar o
que teu código faz
● Bons programadores comentam o código

10. Talvez estejamos
fazendo isso errado
Será que usamos
comentários corretamente?

11. Guia Básico de
Sobrevivência
Sem Comentários

12. Tornando o código inteligível,
adicionando comentários
tornado-o auto-explicativo

13. Comentário Inútil
Explicando a linguagem
Também conhecido
como “talento para
explicar o óbvio”

14. Comentário Inútil
Explicando a linguagem
Sabor Java
São independentes de
plataforma e linguagem

15. Experimente
Linhas em branco, por exemplo
Troque seu comentário
por uma linha em
branco (menos é mais)

16. … se os construtos da
linguagem não são claros,
então precisamos é de
treinamentos e não de
comentários

17. Pérolas nos Comentários
Alguém já viu
a série “pracas do
braziu”?

18. … as aulas de português
são importantes -- e as de
inglês também

19. Comentários para
explicar a API

20. Documente a API
Usando uma api doctool (phpDocumentor,
javadoc, doxygen) para processar os fontes é
possível ter uma documentação da API

21. Documente a API

22. Documente a API

23. Evolua os comentários seguindo
padrões de formatação, para
fornecer uma documentação da
API.

24. Maus cheiros no código
Code Smell:
“a superfície de um problema mais grave
em um sistema”
-- Kent Beck.

25. Comentário Desodorante
Para disfarçar um mau cheiro,
inclusive no código

26. Se o código é claro
suficiente, não é preciso
adicionar comentários

27. Se o código é claro
suficiente, não é preciso
adicionar comentários

28. Desodorante
explicando uma variável
Desnecessário e pouco eficiente. Já pensou
encontrar uma variável $ua no fim do arquivo?

29. Refatoração
renomear!
Use um nome auto-explicativo, sem preguiça ok?
Não faça isso:
Faça assim:

30. Desodorante
explicando um literal

31. Refatoração
introduzir uma constante

32. Desodorante
explicando um método

33. Refatoração
renomear ou documentar
Use recursos da linguagem, como valores padrão,
ajuda a revelar a intenção

34. Comentários explicando as opções
disponíveis

35. Refatoração
introduzir constantes

36. Desodorante
explicando expressões condicionais

37. Refatoração
variável explicativa e/ou …
… introduzir métodos consulta

38. Importante
código como uma prosa > c0d1g0

39. Importante
código como uma prosa > c0d1g0

40. Sempre que estiver por adicionar um
comentário pergunte a si mesmo:
como posso melhorar este código para
que este comentário não seja mais
necessário?

41. Subvertendo Comentários
coisas para que não foram feitos

42. Comentários para não excluir código
e manter o histórico de alterações

43. Solução
usar sistema de versionamento

44. Preservar as versões
anteriores é tarefa de um
Version Control System,
por exemplo: git, subversion ou
até o team foundation version
control

45. Comentários
“tenho que voltar aqui”

46. Solução
usar rótulos ou task tool

47. Use um Sistema de
Gerenciamento de Tarefas,
ou pelo menos o sistema de todo
de sua ferramenta

48. Neo vs Vintage

49. Chistes, trocadilhos e drama
// Querido colega
// Quando terminar de tentar "otimizar" essa rotina e perceber que
// erro terrível foi, por favor, incremente o seguinte contador
// como um aviso ao próximo que tentar:
const total_horas_perdidas_aqui = 42;
double penetration; // ui!
float boat; // deixe float, senão afunda haha!
// Quando eu escrevi isso só eu e Deus
// sabiamos o que estavamos fazendo
// Agora, só Deus sabe!

50. O que ficou de fora …
● Comentários executáveis (!)
● Comentários ofensivos
● Comentários chat
● Comentários sobre comentários

51. // não comente seu código …
// a não ser
● Comentários para aprender, toy projects
● Comentários para documentar API
● Comentários temporários, TODO, FIXME
● Comentários para ajudar os newbies a
contribuir para o software livre

52. Comentários para explicar algoritmos
complexos e/ou decisões de projeto

55. Tá, deu.
Perguntas?