Tema: coding-practice
-
Como projetar uma ferramenta de linha de comando em Python: argparse, main() e códigos de saída
Coloque a interface em uma função main(argv) -> int registrada como console script, valide com type e choices do argparse, siga a convenção de códigos de saída (0 sucesso, 2 erro de uso, 1 demais falhas, códigos sysexits só se documentados), mantenha resultados em stdout e diagnósticos em stderr, e trate SIGINT e broken pipes.
-
Convenções de injeção de dependência no .NET: tempos de vida, escopos e a armadilha da dependência capturada
O Microsoft.Extensions.DependencyInjection registra serviços em um IServiceCollection com tempo de vida transient, scoped ou singleton e os injeta por construtores públicos. As regras documentadas: nunca injetar um serviço scoped em um singleton, deixar o contêiner descartar o que ele criou, evitar chamadas de service locator e validar os escopos para que dependências capturadas falhem na inicialização em vez de vazarem estado entre requisições.
-
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.
-
Refatoração em passos pequenos e verificados
Refatorar muda a estrutura sem alterar o comportamento; fazê-lo em passos minúsculos, com os testes passando entre um passo e outro, e manter commits de refatoração separados dos de mudança de comportamento torna o processo seguro e fácil de revisar.
-
Dívida técnica como decisão consciente, com registro contábil
A metáfora de Cunningham trata código ainda não totalmente correto como um empréstimo, e cada minuto de trabalho extra nele é o juro. Só funciona se a dívida for assumida de forma consciente, registrada e reavaliada com regularidade; como rótulo para tudo o que é feio ou como desculpa para desleixo, não vale nada.
-
Práticas de trabalho para um agente de IA que altera uma base de código
Ler antes de escrever, reproduzir antes de corrigir, alterar em passos pequenos e verificados, executar as verificações do próprio projeto, nunca repetir escritas às cegas e relatar exatamente o que foi testado: uma metodologia para agentes que editam código.
-
Narrowing no TypeScript: unions, unknown e any
O TypeScript reduz um tipo union dentro de um ramo após verificações com typeof, instanceof, in, igualdade e truthiness, ou com um type predicate definido pelo usuário; uniões discriminadas com uma verificação de never garantem exaustividade. unknown aceita qualquer valor, mas proíbe usá-lo até ser estreitado, enquanto any desliga a verificação.
-
Dívida técnica como metáfora e como decisão
A dívida técnica descreve o custo futuro de um atalho. A metáfora é útil quando a dívida é deliberada e registrada, e enganosa quando serve de desculpa para trabalho descuidado ou é usada para descrever qualquer imperfeição.
-
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.
-
Nomes e capitalização consistentes nos campos JSON
Escolha uma única convenção de capitalização para os nomes de propriedades e aplique-a em toda parte: o guia de estilo JSON do Google e o ProtoJSON usam lowerCamelCase, e muitas APIs usam snake_case. Além da capitalização, use nomes significativos, enums como strings, timestamps como strings RFC 3339 e inteiros de 64 bits como strings.
-
Gerenciadores de contexto em Python: como garantir a liberação de recursos
A instrução with executa __enter__ e __exit__ em torno de um bloco, de modo que arquivos, locks e conexões sejam liberados mesmo quando ocorre uma exceção; contextlib.contextmanager transforma um gerador em um gerenciador de contexto.
-
Validando JSON com JSON Schema
O JSON Schema descreve a estrutura permitida de um documento (tipos, chaves obrigatórias, enumerações, formatos, limites) e permite validar entradas em qualquer linguagem antes de processá-las; convém declarar additionalProperties de forma explícita.
-
Docstrings úteis para ferramentas e leitores
A PEP 257 define onde os docstrings ficam e como são formatados; um estilo consistente (Google ou NumPy), com resumo de uma linha, descrição dos argumentos e do retorno e das exceções lançadas, torna-os úteis para leitores, editores e geradores de documentação.
-
Números de ponto flutuante: por que 0.1 + 0.2 não é 0.3
O ponto flutuante binário representa a maioria das frações decimais apenas de forma aproximada, e por isso a aritmética acumula erros de arredondamento. Compare com tolerância, some com cuidado, use inteiros ou tipos decimais para dinheiro e contagens e imprima com dígitos suficientes para que o valor possa ser convertido de volta sem perdas (round-trip).
-
Formatação e linting automatizados como contrato da equipe
Delegar o layout a um formatador e as verificações mecânicas a um linter tira as discussões de estilo do code review; EditorConfig, PEP 8 e ferramentas como o Ruff mostram como codificar esse contrato no repositório.
-
Escalonamento de features e codificação categórica: o que transformar, ajustando apenas com os dados de treino
Modelos baseados em distância ou em gradiente exigem features numéricas em escalas comparáveis (StandardScaler, MinMaxScaler, RobustScaler); colunas categóricas viram números por one-hot, ordinal ou target encoding, conforme a cardinalidade e o tipo de modelo. Todo transformador é ajustado (fit) no conjunto de treino e aplicado sem alterações às linhas de validação, teste e produção.
-
Classes Protocol: tipagem estrutural para o duck typing em Python
Um typing.Protocol declara os métodos e atributos de que um consumidor precisa; qualquer objeto que os tenha satisfaz o tipo sem herdar dele. Defina protocols junto ao código que depende deles, mantenha-os mínimos e use runtime_checkable apenas onde isinstance for realmente necessário.
-
Reprodutibilidade de um experimento de machine learning: seeds, ambiente, dados e os limites do determinismo
Para repetir um experimento e obter o mesmo número, é preciso fixar estados aleatórios passados de forma explícita, fixar versões de bibliotecas, identificar o dataset e a divisão dos dados, e ter em mente que kernels de GPU e novas versões de bibliotecas ainda podem alterar os resultados; o protocolo torna as execuções repetíveis onde possível e documenta onde não são.
-
Extração estruturada de documentos com JSON Schema, validação e tentativas limitadas
Defina o registro de destino como um JSON Schema com additionalProperties false, peça ao modelo exatamente essa forma, valide cada resposta com um validador de verdade, repita um número limitado de vezes incluindo o erro de validação no prompt e encaminhe a uma pessoa o que ainda falhar, em vez de adivinhar.
-
NULL em SQL: lógica de três valores e suas armadilhas
NULL significa desconhecido, então comparações com NULL resultam em desconhecido, e não em verdadeiro ou falso: filtros WHERE descartam as linhas cuja condição é desconhecida, NOT IN com um NULL não retorna nada e agregações ignoram NULLs. Use IS NULL, IS DISTINCT FROM e COALESCE de forma deliberada.
Legível por máquina: JSON