Como escrever comentários que expliquem decisões no código.
Comentários devem explicar a intenção ou uma restrição pouco óbvia. Repetir uma linha simples de código em prosa acrescenta ruído.
Adapte o fluxo à sua tarefa.
Identifique a razão, invariante ou restrição não óbvia do código e explique perto da operação relevante. Remova comentários que apenas narram sintaxe simples e alinhe a explicação ao comportamento real.
- O que você fornece
- Código e estilo de documentação do projeto.
- O que você recebe
- Comentários úteis que explicam intenção e restrições.
Veja a entrada e o resultado.
Entrada e saída ilustrativas · exemplo didático, não uma execução real do WebAct
Exemplo campo
Add an intent comment to this JavaScript mapping. Original row IDs must remain available so reviewers can trace comparison results to their sources.
const copied = rows.map(row => ({ ...row }));Exemplo completo
// Retain source row IDs so reviewers can trace each comparison finding.
const copied = rows.map(row => ({ ...row }));
The comment explains why the IDs remain. The code still makes shallow copies; nested objects are shared.Carregue esta entrada no prompt e copie para o WebAct para testar a tarefa. Seu resultado pode ser diferente da ilustração.
Decisões e solução de problemas.
Toda atribuição deve receber um comentário?
Comente onde intenção ou restrição ficariam pouco claras. Repetir código em prosa acrescenta manutenção sem explicar uma decisão.
Por que um comentário útil se torna enganoso após uma refatoração?
Revise-o junto ao comportamento alterado e atualize ou remova hipóteses antigas. Comentários fazem parte da explicação mantida.
Teste com sua própria fonte.
Substitua o exemplo pelo seu material no prompt. Mantenha os requisitos necessários e copie a tarefa para o WebAct.
Personalizar e copiar a tarefa ↑