{"id":102,"date":"2026-07-20T10:13:10","date_gmt":"2026-07-20T10:13:10","guid":{"rendered":"https:\/\/demensdeum.com\/blog\/2026\/07\/20\/manual-is-your-best-friend\/"},"modified":"2026-07-20T10:13:10","modified_gmt":"2026-07-20T10:13:10","slug":"manual-is-your-best-friend","status":"publish","type":"post","link":"https:\/\/demensdeum.com\/blog\/pt\/2026\/07\/20\/manual-is-your-best-friend\/","title":{"rendered":"Por que a documenta\u00e7\u00e3o \u00e9 sua melhor amiga"},"content":{"rendered":"<p>(e como criar solu\u00e7\u00f5es que continuem funcionando ap\u00f3s as atualiza\u00e7\u00f5es)<\/p>\n<p>&#8220;Os aplicativos s\u00f3 podem usar APIs p\u00fablicas e devem ser executados no sistema operacional atualmente enviado.&#8221; Diretrizes de revis\u00e3o de aplicativos da Apple<\/p>\n<p>Se voc\u00ea j\u00e1 come\u00e7ou a trabalhar com um novo framework e se pegou pensando: \u201cAgora vou entender tudo sozinho, ler a documenta\u00e7\u00e3o \u00e9 muito longo\u201d, voc\u00ea definitivamente n\u00e3o est\u00e1 sozinho. Muitos de n\u00f3s temos um instinto investigativo natural: tente primeiro e s\u00f3 depois leia as instru\u00e7\u00f5es. E isso \u00e9 completamente normal.<\/p>\n<p>No entanto, nesta fase pode ser f\u00e1cil deixar-se levar e acabar numa situa\u00e7\u00e3o em que o c\u00f3digo funciona muito bem, mas talvez dependa de caracter\u00edsticas n\u00e3o \u00f3bvias do sistema.<\/p>\n<h2>Por que \u00e0s vezes n\u00e3o \u00e9 suficiente simplesmente \u201cdescobrir por conta pr\u00f3pria\u201d?<\/h2>\n<p>Frameworks, especialmente os fechados, s\u00e3o sistemas complexos e de m\u00faltiplas camadas. Freq\u00fcentemente, eles ocultam l\u00f3gica interna e otimiza\u00e7\u00f5es que:<\/p>\n<p>* n\u00e3o est\u00e3o descritos em documenta\u00e7\u00e3o p\u00fablica;<br \/>\n* n\u00e3o garantem que o comportamento ser\u00e1 mantido no futuro;<br \/>\n*pode sofrer altera\u00e7\u00f5es com o lan\u00e7amento de novas vers\u00f5es;<br \/>\n* pode conter recursos conhecidos pelos desenvolvedores que ainda n\u00e3o foram corrigidos.<\/p>\n<p>Quando agimos intuitivamente, existe o risco de construirmos arquitetura com base em observa\u00e7\u00f5es aleat\u00f3rias e n\u00e3o em regras documentadas. Isso pode tornar o c\u00f3digo mais sens\u00edvel a atualiza\u00e7\u00f5es.<\/p>\n<h2>A documenta\u00e7\u00e3o n\u00e3o \u00e9 uma limita\u00e7\u00e3o, mas um suporte confi\u00e1vel<\/h2>\n<p>Os desenvolvedores de frameworks criam manuais para nos ajudar. Atuando dentro da documenta\u00e7\u00e3o, obtemos:<\/p>\n<p>* estabilidade;<br \/>\n* apoiar;<br \/>\n* comportamento previs\u00edvel do sistema.<\/p>\n<p>Ao ultrapassar esses limites, assumimos riscos adicionais e a manuten\u00e7\u00e3o desse c\u00f3digo torna-se mais dif\u00edcil.<\/p>\n<p>Experimentos? Certamente. Mas com uma compreens\u00e3o dos limites.<br \/>\nA curiosidade \u00e9 uma \u00f3tima caracter\u00edstica para se ter em um desenvolvedor. Explorar e experimentar coisas novas \u00e9 absolutamente essencial. Mas aqui est\u00e1 um pequeno desejo:<\/p>\n<p>A maneira mais confort\u00e1vel de experimentar \u00e9 confiar nas melhores pr\u00e1ticas.<\/p>\n<p>A documenta\u00e7\u00e3o \u00e9 um mapa que mostra quais caminhos s\u00e3o mais seguros e suportados pelos criadores.<\/p>\n<h2>Uma perspectiva externa: aconselhamento especializado<\/h2>\n<p>Muitas vezes aprendemos com colegas experientes:<\/p>\n<p>* eles conduzem cursos \u00fateis,<br \/>\n* falar em confer\u00eancias,<br \/>\n* escrever livros e blogs maravilhosos,<br \/>\n* compartilhe sua vis\u00e3o \u00fanica.<\/p>\n<p>Muitos deles compartilham experi\u00eancias verdadeiramente valiosas. Mas vale lembrar: se as abordagens do autor contrariarem a documenta\u00e7\u00e3o oficial, podem revelar-se fr\u00e1geis.<\/p>\n<p>Esses \u201cpadr\u00f5es emp\u00edricos\u201d \u00e0s vezes:<\/p>\n<p>* trabalhar apenas em uma vers\u00e3o espec\u00edfica do framework;<br \/>\n* sens\u00edvel a atualiza\u00e7\u00f5es;<br \/>\n* pode se comportar de maneira imprevis\u00edvel em situa\u00e7\u00f5es incomuns.<\/p>\n<p>Aprender com a comunidade \u00e9 \u00f3timo e gratificante. Mas qualquer conselho, mesmo o mais confi\u00e1vel, deve sempre ser cuidadosamente verificado nos manuais oficiais.<\/p>\n<h2>Um pouco sobre SOLID<\/p>\n<h2><\/h2>\n<p>Tr\u00eas ideias dos princ\u00edpios SOLID complementam perfeitamente esta abordagem:<\/p>\n<p>* Princ\u00edpio Aberto\/Fechado: Tente estender o comportamento por meio de APIs p\u00fablicas e, se poss\u00edvel, n\u00e3o dependa de implementa\u00e7\u00e3o oculta.<br \/>\n* Princ\u00edpio da Substitui\u00e7\u00e3o de Liskov: Confie no contrato, n\u00e3o na implementa\u00e7\u00e3o espec\u00edfica. Caso contr\u00e1rio, as mudan\u00e7as ocultas podem levar a dificuldades inesperadas.<br \/>\n* Invers\u00e3o de Depend\u00eancias: crie depend\u00eancias em abstra\u00e7\u00f5es, n\u00e3o em detalhes.<\/p>\n<p>Na pr\u00e1tica, isso significa que estar vinculado a detalhes internos e n\u00e3o documentados da estrutura torna o sistema fr\u00e1gil.<br \/>\nCom base em interfaces p\u00fablicas e contratos, obtemos:<\/p>\n<p>* melhor isolamento do c\u00f3digo de mudan\u00e7as na estrutura;<br \/>\n* facilidade de teste;<br \/>\n* previsibilidade e confiabilidade da arquitetura.<\/p>\n<h2>E se houver um bug?<\/h2>\n<p>Acontece tamb\u00e9m que tudo \u00e9 feito de acordo com as regras, mas o resultado n\u00e3o atende \u00e0s expectativas. Os frameworks evoluem e nem sempre s\u00e3o perfeitos. Nesses casos:<\/p>\n<p>* Construa um exemplo m\u00ednimo que reproduza o problema.<br \/>\n* Certifique-se de que apenas APIs documentadas sejam usadas.<br \/>\n* Envie um relat\u00f3rio de bug &#8211; a equipe de desenvolvimento certamente apreciar\u00e1 seu trabalho e tentar\u00e1 ajudar.<\/p>\n<p>Se o exemplo depender de solu\u00e7\u00f5es alternativas, ser\u00e1 muito mais dif\u00edcil para os desenvolvedores fornecerem suporte.<\/p>\n<h2>Como aproveitar ao m\u00e1ximo a estrutura<\/h2>\n<p>*Consulte a documenta\u00e7\u00e3o.<br \/>\n* Siga os guias e recomenda\u00e7\u00f5es dos autores.<br \/>\n* Experimente a funcionalidade descrita.<br \/>\n* Verifique conselhos da Internet com fontes oficiais.<br \/>\n* Localize bugs respeitando os contratos-quadro.<\/p>\n<h2>Conclus\u00e3o<\/h2>\n<p>Frameworks s\u00e3o ferramentas poderosas com suas pr\u00f3prias regras de jogo. Ao esquec\u00ea-los, corremos o risco de tornar nosso c\u00f3digo excessivamente vulner\u00e1vel. Mas todos n\u00f3s queremos que os produtos criados durem muito tempo e n\u00e3o exijam corre\u00e7\u00f5es urgentes ap\u00f3s cada pequena atualiza\u00e7\u00e3o.<\/p>\n<p>Manuais e documenta\u00e7\u00e3o s\u00e3o um excelente suporte que ajuda a criar solu\u00e7\u00f5es verdadeiramente confi\u00e1veis.<\/p>\n<h2>Fontes<\/h2>\n<p><a href=\"https:\/\/developer.apple.com\/app-store\/review\/guidelines\/\" rel=\"noopener\" target=\"_blank\">https:\/\/developer.apple.com\/app-store\/review\/guidelines\/<\/a><br \/>\n<a href=\"https:\/\/en.wikipedia.org\/wiki\/SOLID\" rel=\"noopener\" target=\"_blank\">https:\/\/en.wikipedia.org\/wiki\/SOLID<\/a><br \/>\n<a href=\"https:\/\/en.wikipedia.org\/wiki\/API\" rel=\"noopener\" target=\"_blank\">https:\/\/en.wikipedia.org\/wiki\/API<\/a><br \/>\n<a href=\"https:\/\/en.wikipedia.org\/wiki\/RTFM\" rel=\"noopener\" target=\"_blank\">https:\/\/en.wikipedia.org\/wiki\/RTFM<\/a><\/p>\n","protected":false},"excerpt":{"rendered":"<p>(e como criar solu\u00e7\u00f5es que continuem funcionando ap\u00f3s as atualiza\u00e7\u00f5es) &#8220;Os aplicativos s\u00f3 podem usar APIs p\u00fablicas e devem ser executados no sistema operacional atualmente enviado.&#8221; Diretrizes de revis\u00e3o de aplicativos da Apple Se voc\u00ea j\u00e1 come\u00e7ou a trabalhar com um novo framework e se pegou pensando: \u201cAgora vou entender tudo sozinho, ler a documenta\u00e7\u00e3o [&hellip;]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[8],"tags":[],"class_list":["post-102","post","type-post","status-publish","format-standard","hentry","category-notes"],"translation":{"provider":"WPGlobus","version":"3.0.5","language":"pt","enabled_languages":["en","ru","zh","de","ja","fr","es","pt","hi"],"languages":{"en":{"title":true,"content":true,"excerpt":false},"ru":{"title":true,"content":true,"excerpt":false},"zh":{"title":true,"content":true,"excerpt":false},"de":{"title":true,"content":true,"excerpt":false},"ja":{"title":true,"content":true,"excerpt":false},"fr":{"title":true,"content":true,"excerpt":false},"es":{"title":false,"content":false,"excerpt":false},"pt":{"title":true,"content":true,"excerpt":false},"hi":{"title":true,"content":true,"excerpt":false}}},"_links":{"self":[{"href":"https:\/\/demensdeum.com\/blog\/pt\/wp-json\/wp\/v2\/posts\/102","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/demensdeum.com\/blog\/pt\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/demensdeum.com\/blog\/pt\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/demensdeum.com\/blog\/pt\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/demensdeum.com\/blog\/pt\/wp-json\/wp\/v2\/comments?post=102"}],"version-history":[{"count":0,"href":"https:\/\/demensdeum.com\/blog\/pt\/wp-json\/wp\/v2\/posts\/102\/revisions"}],"wp:attachment":[{"href":"https:\/\/demensdeum.com\/blog\/pt\/wp-json\/wp\/v2\/media?parent=102"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/demensdeum.com\/blog\/pt\/wp-json\/wp\/v2\/categories?post=102"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/demensdeum.com\/blog\/pt\/wp-json\/wp\/v2\/tags?post=102"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}