Por que comentar em pseudocódigo (e o que um comentário deve entregar)
Em pseudocódigo, comentários existem para registrar intenção e restrições que não ficam óbvias apenas lendo os passos. Um bom comentário responde a pelo menos uma destas perguntas:
- Por quê? (motivação de uma decisão)
- O quê é garantido? (invariantes e regras de negócio)
- O que assumimos? (pré-condições e suposições)
- O que pode dar errado? (limites, casos especiais, riscos)
- O que muda fora? (efeitos colaterais)
Comentários não devem competir com o pseudocódigo. Se o comentário apenas repete o que a linha já diz, ele vira ruído e envelhece rápido.
Convenções: comentário de linha e comentário de bloco
Comentário de linha única
Use para observações curtas e localizadas, coladas ao trecho que elas explicam.
// Regra de negócio: clientes VIP não pagam freteComentário de bloco
Use para contextualizar um trecho maior (um algoritmo, uma função, um laço ou uma decisão complexa). Mantenha curto e estruturado.
/* Validação de entrada: rejeitar valores fora do intervalo permitido (1..12) */Regras práticas de formatação
- Coloque o comentário imediatamente antes do trecho a que se refere (ou ao lado, se for muito curto).
- Prefira frases objetivas, começando por um verbo ou rótulo: “Regra: …”, “Assume: …”, “Invariante: …”.
- Evite comentários longos dentro de loops; se necessário, use um bloco antes do loop.
- Se o comentário descreve um conceito recorrente, padronize o vocabulário (ver seção de vocabulário).
Quando comentar: checklist de alto valor
1) Regras de negócio (o “porquê” do comportamento)
Comente quando a lógica depende de uma regra externa ao algoritmo (política, contrato, legislação, regra comercial).
- Ouça o áudio com a tela desligada
- Ganhe Certificado após a conclusão
- + de 5000 cursos para você explorar!
Baixar o aplicativo
// Regra: cancelamento é permitido até 24h antes do evento2) Invariantes (o que deve permanecer verdadeiro)
Invariantes ajudam a entender e verificar loops e estruturas de dados.
/* Invariante: saldo nunca pode ficar negativo durante a simulação */3) Suposições e pré-condições (o que o algoritmo espera receber)
Quando o algoritmo depende de uma condição de entrada, registre explicitamente. Isso evita “bugs por suposição”.
// Assume: listaDeItens está ordenada por data crescente4) Motivação de decisões (trade-offs e escolhas)
Quando você escolhe um caminho por desempenho, simplicidade, precisão, custo ou limitação do ambiente, registre o motivo.
// Escolha: usar busca linear porque N <= 50 e reduz complexidade de implementação5) Limites, casos especiais e riscos conhecidos
Comente quando há comportamento intencional em bordas (ex.: arredondamento, empates, tolerâncias).
// Empate: se duas opções têm o mesmo custo, escolher a de menor prazo6) Efeitos colaterais (o que muda fora do retorno)
Se o algoritmo altera estado externo (arquivo, banco, cache, log, variável global), documente.
// Efeito colateral: atualiza estoqueGlobal e registra auditoriaQuando evitar: comentários redundantes e “poluentes”
Evite comentários que:
- Repetem o que o pseudocódigo já diz.
- Explicam o óbvio (“incrementa i”).
- São vagos (“faz validação”, “trata erro”).
- Viraram mentira (não acompanham mudanças).
- Servem como “diário” (“alterado por Fulano”).
Exemplo: comentário redundante vs. comentário útil
// RUIM: redundante (não agrega informação nova) total = total + valor // soma valor ao total // BOM: explica intenção/regra // Regra: total deve incluir taxa de serviço de 10% quando tipoPedido = "mesa" SE tipoPedido = "mesa" ENTAO total = total + (valor * 0.10) FIMSEExemplo: comentário vago vs. comentário verificável
// RUIM: vago // validar dados SE idade < 0 ENTAO ERRO "idade inválida" FIMSE // BOM: específico e testável // Pré-condição: idade deve estar no intervalo [0..130] SE idade < 0 OU idade > 130 ENTAO ERRO "idade fora do intervalo" FIMSEDocumentação breve no topo de algoritmos e funções (entradas, saídas e efeitos)
Uma documentação curta no topo reduz a necessidade de comentários espalhados. O objetivo é permitir que alguém entenda o “contrato” em poucos segundos.
Modelo recomendado (3 a 8 linhas)
/* Objetivo: o que esta rotina resolve em uma frase Entradas: principais parâmetros (tipo/unidade/restrições) Saídas: retorno e significado Efeitos colaterais: alterações externas (se houver) Erros: condições que geram erro/retorno especial (opcional) */Exemplo completo
/* Objetivo: calcular o valor final do pedido com descontos e frete Entradas: itens (lista com precoUnitario, quantidade), cepDestino (texto), ehVIP (booleano) Saídas: totalFinal (número >= 0) Efeitos colaterais: nenhum Erros: erro se itens estiver vazio ou quantidade <= 0 */ FUNCAO CalcularTotalFinal(itens, cepDestino, ehVIP) SE itens estiver vazio ENTAO ERRO "pedido sem itens" FIMSE total = 0 PARA cada item EM itens FACA SE item.quantidade <= 0 ENTAO ERRO "quantidade inválida" FIMSE total = total + (item.precoUnitario * item.quantidade) FIMPARA // Regra: VIP não paga frete SE ehVIP = VERDADEIRO ENTAO frete = 0 SENAO frete = CalcularFretePorCEP(cepDestino) // Assume: função retorna número >= 0 FIMSE // Regra: desconto progressivo por total (valores em moeda) SE total >= 500 ENTAO desconto = total * 0.10 SENAO SE total >= 200 ENTAO desconto = total * 0.05 SENAO desconto = 0 FIMSE totalFinal = (total - desconto) + frete RETORNAR totalFinal FIMFUNCAOPasso a passo prático para documentar uma rotina
Escreva o objetivo em 1 frase: comece com um verbo (“calcular”, “validar”, “gerar”, “selecionar”).
Liste entradas com restrições: inclua unidade/intervalo quando relevante (ex.: “idade [0..130]”, “taxa em %”).
Defina a saída: nome, tipo e significado (não apenas “retorna número”).
Declare efeitos colaterais: “nenhum” também é informação útil.
Registre erros/retornos especiais: condições que interrompem ou mudam o fluxo.
Revise para remover redundância: se uma linha do topo repete o óbvio, corte; se falta uma regra importante, adicione.
Comentários bons vs. poluentes: comparações rápidas
| Situação | Comentário poluente | Comentário bom |
|---|---|---|
| Nome de variável já é claro | // define total | // Regra: total não inclui impostos; impostos são adicionados no fechamento |
| Condição simples | // verifica se é maior | // Limite: valores iguais são tratados como aprovados |
| Tratamento de erro | // trata erro | // Erro: se token expirar, exigir novo login (não tentar renovar automaticamente) |
| Loop | // percorre a lista | /* Invariante: melhorOpcao guarda o menor custo encontrado até agora */ |
| Decisão de implementação | // usar este método | // Escolha: ordenar por data para garantir processamento determinístico |
Padronização de vocabulário para reduzir ambiguidade
Ambiguidade em comentários cria interpretações diferentes do mesmo requisito. Padronizar termos evita discussões e erros de implementação.
Estratégia prática
- Defina um mini-glossário de termos recorrentes do domínio (2 a 10 termos).
- Use sempre o mesmo termo para o mesmo conceito (não alternar “cliente”, “usuário”, “comprador” se significam a mesma entidade).
- Quando houver termos parecidos, diferencie com precisão (ex.: “cancelar” vs “estornar”).
- Padronize palavras-chave nos comentários:
Regra:,Assume:,Invariante:,Limite:,Efeito colateral:,Erro:.
Mini-glossário (exemplo para pedidos e pagamentos)
| Termo | Definição padronizada | Evitar usar como sinônimo |
|---|---|---|
| Pedido | Conjunto de itens + dados de entrega/pagamento | Compra, carrinho (se forem estados diferentes) |
| Item | Produto + quantidade dentro do pedido | Produto (produto é o catálogo) |
| Cancelar | Interromper antes de faturar/entregar | Estornar |
| Estornar | Reverter cobrança já realizada | Cancelar |
| Frete | Custo de entrega calculado por CEP/peso | Taxa (se taxa for outra cobrança) |
| Taxa de serviço | Percentual adicional aplicado em pedidos “mesa” | Imposto (se imposto for tributo) |
Exemplo: ambiguidade e correção
// RUIM: termo ambíguo // aplicar taxa no total total = total + taxa // BOM: termo definido e regra explícita // Regra: aplicar taxa de serviço (10%) apenas quando tipoPedido = "mesa" SE tipoPedido = "mesa" ENTAO total = total + (total * 0.10) FIMSE
