Por que a documentação é sua melhor amiga

(e como criar soluções que continuem funcionando após as atualizações)

“Os aplicativos só podem usar APIs públicas e devem ser executados no sistema operacional atualmente enviado.” Diretrizes de revisão de aplicativos da Apple

Se você já começou a trabalhar com um novo framework e se pegou pensando: “Agora vou entender tudo sozinho, ler a documentação é muito longo”, você definitivamente não está sozinho. Muitos de nós temos um instinto investigativo natural: tente primeiro e só depois leia as instruções. E isso é completamente normal.

No entanto, nesta fase pode ser fácil deixar-se levar e acabar numa situação em que o código funciona muito bem, mas talvez dependa de características não óbvias do sistema.

Por que às vezes não é suficiente simplesmente “descobrir por conta própria”?

Frameworks, especialmente os fechados, são sistemas complexos e de múltiplas camadas. Freqüentemente, eles ocultam lógica interna e otimizações que:

* não estão descritos em documentação pública;
* não garantem que o comportamento será mantido no futuro;
*pode sofrer alterações com o lançamento de novas versões;
* pode conter recursos conhecidos pelos desenvolvedores que ainda não foram corrigidos.

Quando agimos intuitivamente, existe o risco de construirmos arquitetura com base em observações aleatórias e não em regras documentadas. Isso pode tornar o código mais sensível a atualizações.

A documentação não é uma limitação, mas um suporte confiável

Os desenvolvedores de frameworks criam manuais para nos ajudar. Atuando dentro da documentação, obtemos:

* estabilidade;
* apoiar;
* comportamento previsível do sistema.

Ao ultrapassar esses limites, assumimos riscos adicionais e a manutenção desse código torna-se mais difícil.

Experimentos? Certamente. Mas com uma compreensão dos limites.
A curiosidade é uma ótima característica para se ter em um desenvolvedor. Explorar e experimentar coisas novas é absolutamente essencial. Mas aqui está um pequeno desejo:

A maneira mais confortável de experimentar é confiar nas melhores práticas.

A documentação é um mapa que mostra quais caminhos são mais seguros e suportados pelos criadores.

Uma perspectiva externa: aconselhamento especializado

Muitas vezes aprendemos com colegas experientes:

* eles conduzem cursos úteis,
* falar em conferências,
* escrever livros e blogs maravilhosos,
* compartilhe sua visão única.

Muitos deles compartilham experiências verdadeiramente valiosas. Mas vale lembrar: se as abordagens do autor contrariarem a documentação oficial, podem revelar-se frágeis.

Esses “padrões empíricos” às vezes:

* trabalhar apenas em uma versão específica do framework;
* sensível a atualizações;
* pode se comportar de maneira imprevisível em situações incomuns.

Aprender com a comunidade é ótimo e gratificante. Mas qualquer conselho, mesmo o mais confiável, deve sempre ser cuidadosamente verificado nos manuais oficiais.

Um pouco sobre SOLID

Três ideias dos princípios SOLID complementam perfeitamente esta abordagem:

* Princípio Aberto/Fechado: Tente estender o comportamento por meio de APIs públicas e, se possível, não dependa de implementação oculta.
* Princípio da Substituição de Liskov: Confie no contrato, não na implementação específica. Caso contrário, as mudanças ocultas podem levar a dificuldades inesperadas.
* Inversão de Dependências: crie dependências em abstrações, não em detalhes.

Na prática, isso significa que estar vinculado a detalhes internos e não documentados da estrutura torna o sistema frágil.
Com base em interfaces públicas e contratos, obtemos:

* melhor isolamento do código de mudanças na estrutura;
* facilidade de teste;
* previsibilidade e confiabilidade da arquitetura.

E se houver um bug?

Acontece também que tudo é feito de acordo com as regras, mas o resultado não atende às expectativas. Os frameworks evoluem e nem sempre são perfeitos. Nesses casos:

* Construa um exemplo mínimo que reproduza o problema.
* Certifique-se de que apenas APIs documentadas sejam usadas.
* Envie um relatório de bug – a equipe de desenvolvimento certamente apreciará seu trabalho e tentará ajudar.

Se o exemplo depender de soluções alternativas, será muito mais difícil para os desenvolvedores fornecerem suporte.

Como aproveitar ao máximo a estrutura

*Consulte a documentação.
* Siga os guias e recomendações dos autores.
* Experimente a funcionalidade descrita.
* Verifique conselhos da Internet com fontes oficiais.
* Localize bugs respeitando os contratos-quadro.

Conclusão

Frameworks são ferramentas poderosas com suas próprias regras de jogo. Ao esquecê-los, corremos o risco de tornar nosso código excessivamente vulnerável. Mas todos nós queremos que os produtos criados durem muito tempo e não exijam correções urgentes após cada pequena atualização.

Manuais e documentação são um excelente suporte que ajuda a criar soluções verdadeiramente confiáveis.

Fontes

https://developer.apple.com/app-store/review/guidelines/
https://en.wikipedia.org/wiki/SOLID
https://en.wikipedia.org/wiki/API
https://en.wikipedia.org/wiki/RTFM