Abordagens

Aprenda a escrever abordagens para exercícios

Cada exercício pode ter abordagens associadas a ele, que descrevem as diferentes formas de resolver um exercício.

Abordagem

Uma abordagem deve explorar como um exercício pode ser resolvido de uma determinada maneira.

  • Seu conteúdo deve:
    • Explorar uma abordagem idiomática
    • Explorar uma abordagem não idiomática, mas interessante
  • Começar com um exemplo de código (completo)
    • Usar exemplos de código à vontade no restante do documento
  • Sinta-se à vontade para se aprofundar no tema
  • Incluir links para recursos úteis (por exemplo, documentação)
  • O trecho de código deve mostrar o cerne da abordagem
    • É possível usar no máximo 8 linhas

Se você quiser comparar abordagens diferentes, escreva um artigo.

Visão geral das abordagens

  • Dar contexto ao problema
    • Descrever pontos importantes (por exemplo, pegadinhas) que se aplicam a todas as abordagens
  • Discutir as abordagens mais idiomáticas
  • Cada abordagem deve começar com um trecho de código que a ilustre
  • Manter o conteúdo relativamente geral
    • Informações detalhadas devem ficar em uma página de abordagem separada
    • Incluir um link para a página de abordagem separada para mais informações
  • Discutir como escolher entre as abordagens
    • Quais são os prós e contras?
    • Algumas abordagens são mais adequadas para casos de uso específicos?

Considerações gerais

  • Algumas linguagens têm diferentes formas de escrever a mesma coisa. Se parte dessa sintaxe só ficou disponível em versões mais recentes da linguagem, considere usar a sintaxe "antiga". Assim, é mais provável que os estudantes entendam o código.
    • A sintaxe alternativa pode ser mostrada no documento da abordagem
  • Se a sua linguagem tem um guia de estilo recomendado, siga essas diretrizes (quando possível)

Para quais exercícios escrever abordagens?

Em geral, os Exercícios de Prática são mais adequados para escrever abordagens, já que normalmente podem ser resolvidos de várias maneiras.

Para os Exercícios de Conceito, pode ser interessante discutir a abordagem exemplar. Por exemplo, você pode mostrar como o conceito ensinado torna certo código mais fácil de escrever.

Arquivos

Cada abordagem deve adicionar os dois arquivos a seguir:

  • .approaches/<approach-slug>/content.md: descrição da abordagem (veja a documentação)
  • .approaches/<approach-slug>/snippet.txt: trecho de código que mostra a abordagem (veja a documentação)

Depois, você vai precisar adicionar ou atualizar:

Configurando a extensão do trecho de código

Você também pode usar uma extensão personalizada em vez da extensão padrão .txt, definindo o campo approaches.snippet_extension no arquivo config.json da sua trilha. Se você definir esse campo, o arquivo de trecho de código que precisa adicionar deve se chamar .approaches/<approach-slug>/snippet.<approaches.snippet_extension>.