O fluxo de trabalho principal06 / 16
Ler explicações e evidências
Nesta página
As explicações da implementação ajudam você a partir de uma parte da intenção, entender como o código funciona e encontrar evidências para essa descrição. Foque no comportamento, no material de apoio e nas perguntas que ainda precisam da sua avaliação.
Abra explicações de parágrafo e locais
Clique no texto do documento para editá-lo. Clique no espaço em branco dentro de um parágrafo, fora do texto, para abrir a explicação do parágrafo, identificada como L1.
Algumas explicações se aplicam a uma palavra ou expressão. Passe o ponteiro sobre o parágrafo para revelar sublinhados curtos e clique em um deles para ler sua explicação local, identificada como L2.
Listas, tabelas e blocos de código também podem ter explicações. Uma lista inteira é investigada em conjunto; títulos não são investigados separadamente.
Você pode manter abertas notas à margem de vários parágrafos. Cada parágrafo mostra uma explicação de parágrafo ou local por vez. Em uma janela estreita, a nota pode aparecer abaixo do parágrafo.
Leia as três seções
| Seção | Pergunta que responde | O que observar |
|---|---|---|
| Implementação | Como a implementação atende a esta intenção? | Comportamento, etapas, casos de borda e decisões de implementação. |
| Evidências | O que sustenta a explicação? | Referências de código, testes, saída de comandos e outros materiais que podem ser examinados. |
| Atenção | O que precisa de mais avaliação? | Lacunas, decisões de implementação, riscos e sugestões. |
Implementação fica expandida por padrão. Expanda Evidências quando necessário. Atenção fica oculta quando não há pontos a mostrar.
Para uma recompensa após 7 check-ins consecutivos, a explicação pode descrever como as datas se acumulam, citar a função e os testes relevantes e destacar como viagens entre fusos horários são tratadas. O conteúdo real depende da investigação do seu projeto.
Examine as evidências
Referências de código abrem arquivos no aplicativo padrão do sistema. Imagens podem ser visualizadas e ampliadas na nota à margem. Rótulos de materiais como saída de comandos e diferenças de código abrem uma nova aba. O Noea avisa se o material não está mais disponível.
Pergunte se cada referência responde à sua dúvida, quais condições um teste cobre e se os resultados sustentam a conclusão. Se faltar um cenário importante, pergunte sobre o parágrafo e solicite mais investigação ou verificação.
Em especial, diferencie três tipos de evidências:
| Material | O que ajuda a estabelecer | O que não estabelece |
|---|---|---|
| Código de implementação ou de testes | A lógica usada e os cenários definidos pelos testes. | A existência dos testes não significa que foram executados ou passaram. |
| Resultados de execuções anteriores | O que foi executado naquela ocasião e qual foi o resultado. | Alterações posteriores no código podem tornar esses resultados inaplicáveis. |
| Verificação realmente executada agora | O resultado para o ambiente e o escopo desta execução. | Passar nos cenários cobertos não comprova a correção dos cenários não testados. |
Explicar e Investigação normalmente leem o código e as evidências existentes, em vez de executar novamente testes, compilações ou o aplicativo a cada vez. Verificam um fato quando necessário, se apenas a leitura não permitir estabelecer algo essencial para a avaliação. Avalie o escopo de verificação a partir do que realmente foi executado.
Para executar novamente um teste específico, peça ao Agente na conversa que o execute e informe seu escopo e resultado; depois investigue novamente o parágrafo correspondente.
Decida quais escolhas pertencem à intenção
Uma explicação que diz “A implementação usa atualmente armazenamento local” descreve a abordagem de hoje; ela não exige que versões futuras a utilizem. Requisitos que você quer manter pertencem ao documento de intenção.
Considere se uma escolha afeta a experiência do usuário, o custo, a privacidade, o risco ou decisões futuras. Depois de entendê-la, há dois resultados comuns:
- A abordagem atual é aceitável e você quer deixar espaço para mudá-la depois: continue usando sem torná-la uma restrição.
- A abordagem precisa continuar valendo nas próximas versões: escreva o requisito explicitamente e revise os limites que ele introduz.
Por exemplo, você pode aceitar hoje o armazenamento local dos check-ins. Se o uso sem conexão se tornar essencial, escreva “Os usuários ainda podem fazer check-in sem conexão de rede” e investigue como a implementação permite esse comportamento. Expressar o comportamento exigido costuma ser mais fácil de manter do que copiar uma descrição detalhada da implementação.
Entenda a seção Atenção
Os itens de Atenção são classificados como lacunas, decisões de implementação, riscos ou sugestões. Eles distinguem comportamentos ausentes de decisões atuais de design e assuntos que merecem mais discussão.
O marcador de atenção à direita de um parágrafo abre a explicação correspondente. Seu número conta painéis de explicação com pontos de atenção, não problemas individuais. Uma lacuna dá ao marcador uma cor mais destacada.
Entenda o impacto antes de decidir corrigir o código, acrescentar verificação, mudar a intenção ou manter o comportamento atual. Nem todo ponto de atenção precisa virar requisito. A ausência de marcador significa apenas que a explicação atual não lista nenhum.
Explore ilustrações do comportamento
Algumas explicações incluem uma pequena ilustração interativa do comportamento. Você pode experimentá-la, reiniciá-la ou examinar seu código-fonte.
Essas ilustrações são executadas em um ambiente isolado, sem acesso ao aplicativo ou à rede, e não salvam o estado da interação. Elas explicam uma regra; conferir se o software real a segue ainda exige código e evidências de verificação.
Confira se uma explicação ainda se aplica
Texto anterior significa que a explicação cobre a intenção antes da sua edição. Pode estar desatualizado significa que arquivos lidos ou citados pela explicação mudaram após a investigação. Ambos são motivos para investigar novamente.
As notas à margem são somente leitura. Edite a intenção para mudar um requisito; use Investigação ou Investigar Novamente para conferir uma explicação. Consulte Manter as explicações atualizadas.