32. Código autodocumentado
A melhor documentação é o próprio código; comente a intenção (por quê), não o óbvio (como).
Resumo
- Principal documentação é o estilo: bons nomes, estrutura, rotinas pequenas. Comentário complementa.
- Tipos: repetir o código (ruim), explicar código confuso (melhor reescrever), marcador (tirar antes de entregar).
- Bons: resumo do código e intenção (nível do problema). Úteis: info que o código não expressa (licença, autor).
- Comente no nível da intenção, foque no porquê, documente surpresas e contornos de bugs. Código truque: reescreva.
- Dados: unidades, faixas, significados codificados. Rotinas: propósito, parâmetros, suposições, limitações.
Perguntas-chave
responda de cabeça, depois abraQual tipo de comentário é o mais útil?
O que descreve a intenção do código no nível do problema (por que ele existe e o que busca), seguido do resumo.
O que fazer com código truque (tricky)?
Reescrevê-lo para ficar claro, em vez de explicá-lo com comentários longos.
O que comentar numa declaração de dados?
Unidades de medida, faixa de valores permitidos, significados de códigos, limitações e o uso de dados globais.
Exercícios de fixação
0/5 respondidas1.
Qual comentário é o melhor segundo o capítulo?
2.
Um trecho usa um truque de bits que ninguém entende e tem 10 linhas de comentário explicando. O livro sugere:
3.
Na declaração
double distancia;, o comentário mais útil é:4.
Um
// TODO: rever isto deixado no código é um comentário do tipo:5.
O código contorna um bug conhecido de uma biblioteca com uma linha estranha. O que fazer?