codigo-didatico-ptbr

Imported from werlang/pw1 (.agents/skills/codigo-didatico-ptbr/SKILL.md). Install upstream with npx skills add werlang/pw1 --skill codigo-didatico-ptbr. Copyright stays with the author.

Código Didático PT-BR

Escrever código deste repositório como material de aprendizagem, não como código de produção otimizado.

Partir da ideia de que estudantes do ensino médio podem ler, copiar, adaptar e apresentar esse código em aula. Priorizar clareza, progressão pedagógica e documentação útil.

Objetivo

Produzir código que:

• seja fácil de ler por iniciantes;
• exponha a lógica em passos visíveis;
• ajude o professor a explicar o raciocínio;
• use comentários em PT-BR quando eles realmente ajudarem;
• mantenha consistência com os exemplos e exercícios vizinhos.

Regras obrigatórias

• Assumir autoria estudantil e finalidade educacional em todo código novo.
• Preferir a solução mais simples que ensine bem o conceito pedido.
• Evitar abstrações desnecessárias, truques de linguagem, metaprogramação, helpers genéricos demais e encadeamentos difíceis de explicar.
• Manter mudanças locais à pasta alvo e respeitar o padrão do material ao redor.
• Preservar JavaScript vanilla, DOM direto e o estilo PHP já usado no repositório, salvo pedido explícito em contrário.
• Usar nomes claros e coerentes com o contexto da pasta. Se o material já estiver em português, manter o vocabulário em português.
• Escrever comentários em PT-BR, com ortografia correta e acentuação normal.
• Comentar intenção, fluxo, decisão e armadilha. Não comentar o óbvio linha por linha.
• Em código didático de frontend, não usar atributos data-* nem dataset para acionar comportamentos.
• Para elementos dinâmicos, preferir createElement, append / appendChild, seleção direta de nós criados e addEventListener no próprio elemento.

Fluxo recomendado

1. Ler a pasta alvo e um exemplo, exercício ou README próximo para calibrar profundidade e vocabulário.
2. Identificar qual conceito principal o código deve ensinar.
3. Escolher uma estrutura direta, com poucas camadas de indireção.
4. Implementar em passos pequenos, com funções curtas quando isso melhorar a leitura.
5. Adicionar comentários em PT-BR nos pontos em que um estudante provavelmente teria dúvida.
6. Revisar com o checklist em references/revisao-final.md.

Como escrever código didático

• Mostrar uma ideia por bloco sempre que possível.
• Preferir condicionais explícitas a expressões excessivamente compactas.
• Separar captura de dados, processamento e atualização de interface quando isso ajudar a explicar o fluxo.
• Usar valores de exemplo concretos e legíveis em vez de placeholders abstratos.
• Em exercícios e exemplos, deixar claro o estado principal da aplicação: variáveis, arrays, objetos, sessão, formulário ou DOM.
• Quando houver validação, explicar com comentário curto o motivo da regra.
• Em renderização dinâmica, construir a árvore de nós passo a passo em vez de depender de innerHTML com metadados de ação.

PHP misturado com HTML

• Mantenha dados, cálculos, decisões e laços em um bloco contínuo de PHP sempre que o fluxo for mais longo que uma impressão inline.
• Quando uma decisão ou repetição gerar HTML, faça a impressão necessária dentro desse bloco com echo; depois, feche o PHP e continue com o HTML estático.
• Reserve <?= $variavel ?> para valores simples e curtos dentro de um trecho inline, como o nome de uma pessoa ou um número já calculado.
• Calcule e formate valores antes de entrar no HTML. Evite chamadas como <?= number_format(...) ?> quando elas puderem ser preparadas em uma variável com nome claro.
• Evite fragmentar uma mesma decisão ou repetição com várias aberturas e fechamentos de PHP, especialmente na sintaxe alternativa if (...) : ?> ... <?php endif;.

Exemplo preferível para uma repetição que gera itens:

<ul>
<?php
foreach ($nomes as $nome) {
    echo "<li>$nome</li>";
}
?>
</ul>

Para uma impressão curta, a forma inline continua adequada:

<p>Estudante: <?= $nomeEstudante ?></p>

Como comentar

Usar comentários curtos e úteis, por exemplo:

// Guarda as tarefas em memória para podermos redesenhar a lista sempre que algo mudar.
let tarefas = [];

// Se o campo estiver vazio, não faz sentido criar uma tarefa sem texto.
if (descricao === "") {
    return;
}

// Fecha a sessão do usuário para impedir acesso às páginas protegidas.
session_destroy();

Evitar comentários assim:

// Incrementa i
i++;

Critérios de qualidade

• O arquivo pode ser entendido por alguém que está vendo o conteúdo pela primeira vez.
• O código favorece explicação em aula e manutenção pelo estudante.
• Os nomes ajudam a prever o papel de cada parte.
• Os comentários orientam a leitura sem poluir o arquivo.
• A solução não depende de conhecimento acima do nível esperado para a seção.

Recurso de apoio

Antes de concluir, ler references/revisao-final.md e corrigir qualquer item que ainda não esteja claro o suficiente para uso didático.