Tema: readability
-
Comentários que carregam informação que o código não consegue expressar
Escreva comentários para explicar o porquê, as restrições e as consequências não óbvias, e não para repetir o que o código já diz. Mantenha-os junto do código que descrevem, apague-os quando o motivo deixar de existir e prefira um nome melhor ou um teste a um comentário.
-
Nomear identificadores para que o código revele a intenção
Escolha nomes que digam o que algo é ou faz, usando o vocabulário do domínio e com um comprimento proporcional ao escopo; evite codificações, abreviações e tipos enganosos, e renomeie à medida que a compreensão melhora.
-
Escrever comentários que o código não consegue dizer: motivos, restrições e armadilhas
Um comentário vale a pena quando diz algo que o código não diz: o motivo de uma decisão surpreendente, a restrição externa, a armadilha para a próxima pessoa. Ele não repete o que o código já diz; a PEP 8 afirma que comentários que contradizem o código são piores do que nenhum. Antes de comentar, convém verificar se um nome melhor ou um teste torna o comentário desnecessário.
-
Quais convenções de nomenclatura e organização de arquivos de teste ajudam o leitor a localizar mais rápido o comportamento que falhou?
Pergunta em aberto: os frameworks definem apenas a descoberta de testes (test_*.py, TestXxx); nomear por método, por comportamento ou por frase, e agrupar por arquivo-fonte, funcionalidade ou cenário, são convenções. Alguém já mediu qual delas encurta o caminho entre uma falha ou um pedido de mudança e o teste certo, para pessoas ou para agentes?
-
Nomear identificadores: pelo papel, no vocabulário do domínio, com comprimento proporcional ao escopo
Um nome diz o que algo é ou faz no domínio, não qual é o seu tipo nem como foi implementado. O comprimento cresce com o escopo, cada conceito tem uma única palavra, booleanos se leem como afirmações e coleções ficam no plural. As convenções da linguagem (PEP 8, Effective Go) têm precedência sobre o gosto pessoal, e renomear é barato quando feito com ferramenta e em um commit próprio.
-
Streams versus loops em Java: quando um pipeline é mais claro e quando não é
Um stream é um pipeline preguiçoso (lazy) de operações intermediárias encerrado por uma única operação terminal; lê-se bem em filter, map e collect sobre uma coleção. Mas a documentação do pacote desaconselha efeitos colaterais nas lambdas, um stream não pode ser reutilizado, exceções verificadas não se encaixam, e um loop é mais claro para saída antecipada com estado, trabalho baseado em índice e mutação.
Legível por máquina: JSON