TL; DR poucas coisas ensinam as pessoas melhor do que exemplos de código de trabalho.
teste-os automaticamente!
Qual é o problema?
Ao adquirir uma nova biblioteca, muitas pessoas começam lendo a documentação e, a seguir, escolhem um dos exemplos de código como ponto de partida para seus próprios experimentos. Mas, muitas vezes, os exemplos de código simplesmente não funcionam fora da caixa. Agora você pode perguntar: ok é ver que é um incômodo, mas não é um problema, é? Isto é! A questão é: este exemplo de código poderia ter transformado um leitor de documentação passivo em um usuário ativo . Pode ter sido o ponto de entrada deles na biblioteca, mas a porta estava fechada. A maioria dos programadores realmente deseja ser ativa. Se forem mantidos passivos, ficarão impacientes rapidamente.
Por que os exemplos de código não funcionam fora da caixa?
A maioria dos problemas pode ser aproximadamente o código é …
… está completo, mas incorreto .
A fonte usual é que os mantenedores não verificam seus exemplos regularmente ou nem os verificam. Parte do problema é que algumas ferramentas de documentação fornecem um zilhão de maneiras de renderizar o código, mas nenhuma de realmente executá-lo.
… está correto, mas incompleto ou abstrato .
Em geral, concordo que os exemplos de código devem ser os mais curtos possíveis, mas não mais curtos. Uma prática comum é deixar de lado o código que configura os objetos usados no exemplo ou simplesmente usar espaços reservados. Isso realmente torna o código mais curto . No entanto, aumenta o tempo que alguém tem para olhar o código para entendê-lo, porque leva mais tempo para descobrir as pré-condições corretas. Observe ainda que “exemplo abstrato” é um oxímoro.
O que pode ser feito sobre isso?
Uma primeira abordagem para obter exemplos de código de trabalho é testá-los automaticamente. Muitas ferramentas de documentação já oferecem suporte para isso e outras podem ser facilmente estendidas. Veja a seção de exemplos para diferentes abordagens sobre isso! Minha abordagem usual pode ser descrita da seguinte forma:
O código incorreto geralmente pode ser corrigido simplesmente como uma especificação com falha.
A maioria dos exemplos abstratos ou incompletos podem ser corrigidos adicionando duas linhas de código de inicialização.
Se isso não funcionar. Pense você mesmo: para quem o recurso documentado é relevante?
Se for relevante para o usuário médio , provavelmente o design de sua API está quebrado , porque obviamente torna muito difícil arquivar coisas comuns. Parabéns! Ao procurar exemplos quebrados, você encontrou uma peculiaridade no design da API. Conserte isso!
Se for relevante para o usuário pesado , coloque-o em um arquivo externo e deixe uma nota onde pode ser encontrado. Desta forma, não atrapalha a documentação, mas ainda é acessível.
Se for relevante apenas para o usuário extremamente pesado , remova-o! Esses caras não vão confiar nos exemplos de qualquer maneira e apenas ler o código.
Alguns exemplos
Primeiro, um exemplo de como pode ser simples integrar a validação dos exemplos de código junto com as especificações. Este código é de uma de minhas bibliotecas e testa todos os exemplos de código. Além disso, ele transforma os comentários no exemplo em correspondências rspec simples.
Uma abordagem interessante é realizada atualmente para a biblioteca slim para converter as especificações em código Markdown e testá-los com um leitor Markdown customizado.
Finalmente, relishapp.com fez disso um modelo de negócios! Há um monte de aplicativos em relishapp.com que converteram mais ou menos toda a sua documentação para testes de pepino. Relishapp então testa e apresenta a documentação para eles.