为什么文档是您最好的朋友

（以及更新后的建议不再工作的大师）

“应用程序只能使用公共API，必须在当前运输的操作系统上运行。” Apple App评论指南

如果您曾经开始使用一个新的框架，并让自己思考：“现在我会理解一切，文档是针对孔的” – 您绝对并不孤单。许多开发人员有一个自然的本能：首先尝试，然后才能阅读。这很好。

但是，正是在这个阶段，您可以轻松地关闭正确的道路，发现自己处在代码有效的情况下……但是只有今天，只有“我有”。

为什么“弄清楚”很容易 – 还不够吗？

Freimvorki，尤其是封闭和专有的，是复杂的，多层次的。他们具有许多隐藏的逻辑，优化和实现功能，其中：

*未记录；
*不能保证；
*可以随时改变；
*是商业秘密，可以受到专利保护
*包含错误，仅在框架开发人员中知道的缺陷。

当您“直觉”行动时，您可以轻松地在随机观察中构建体系结构，而不是对清晰描述的规则进行支持。这导致了以下事实：代码变得容易受到更新和边缘案例的影响。

框架的开发人员创建手册是有原因的 – 这是您和他们之间的协议。当您充当文档的一部分时，他们保证：

* 稳定;
* 支持;
*可预测的行为。

如果您超越此框架 – 接下来发生的一切都将完全成为您的责任。

实验？当然。但是在规则的框架内。
好奇心是开发人员的超级视频。探索，尝试非标准，测试边界 – 所有这些都是必要的。但是有一个重要的“但是”：

您需要在文档和最佳实践的框架中进行实验。

文件不是监狱，而是卡。她展示了真正的计划和支持的机会。这种实验不仅有用，而且安全。

有时您可能会遇到真正的“专家”：

*他们开展课程
*在会议上表演，
*写书和博客，
*分享了对框架的“方法”。

但是，即使他们听起来令人信服，也要记住：
如果他们的方法与文档相反，则它们是不稳定的。

这样的“经验模式”可以：

*仅在特定版本的框架上工作；
*容易受到更新的影响；
*在不可预测的情况下打破。

当宗师尊重手册时，他们很酷。否则，必须通过官方文档过滤他们的提示。

来自扎实原则的三个想法在这里特别重要：

*开放/封闭的原则：通过公共API扩展行为，不要进入内部。
* Liskov的变态原则：不要依靠实施，依靠合同。疾病 – 替换实施时，一切都会破裂。
*依赖关系反转：高级别模块不应取决于低级别的模块。两种类型都应取决于抽象。抽象不应取决于细节。细节应取决于抽象。

这在实践中意味着什么？如果您使用框架并直接与其内部细节绑定 – 您违反了此原则。
相反，您需要建立对框架正式支持的公共接口，协议和合同的依赖。这给出了：

*与框架更改中代码的最佳隔离；
*容易测试和替换依赖项的能力；
*架构的可预测行为和稳定性。

当您的代码取决于详细信息，而不是抽象时，您将自己嵌入到可能随时消失或更改的特定实现中。

有时您会做正确的事情，但是它起作用了。发生这种情况 – 框架并不完美。在这种情况下：

*收集一个最小复制的例子。
*确保仅使用已记录的API。
*发送一个错误端口 – 他们肯定会理解您，并且很可能会有所帮助。

如果该示例是建立在黑客或旁路上的，则不需要开发人员支持它，并且很可能您的案件会简单地错过。

*阅读文档。严重地。
*遵循作者的指南和建议。
*实验 – 但在所述。
*通过手册检查技巧（甚至是最著名的演讲者！）。
*折叠漏洞，案件最小并尊重合同。

Freimvorki不是黑匣子，而是具有使用规则的工具。忽略它们意味着“随机”编写代码。但是，我们希望我们的代码长期生活，使用户满意，并且不会从次要更新中脱颖而出。

因此：信任，但是检查。是的，阅读手册。它们是您的超级大国。