Keras 作者：给软件开发者的 33 条黄金法则

> 本文由 [简悦 SimpRead](http://ksria.com/simpread/) 转码， 原文地址 [www.tuicool.com](https://www.tuicool.com/articles/fee6VnQ)

![](https://img0.tuicool.com/3eaueqY.jpg!web)

Keras 作者、谷歌大脑 François Chollet 从软件开发流程、API 设计和职业规划方面给开发者列出的 33 条注意事项，相信可以让你避开很多大坑，一起来看看吧。

关于开发流程

1、代码不仅仅是意味着要执行。代码也是跨团队沟通的一种方式，是向他人描述问题解决方案的一种方式。可读代码是必须的，是编写代码的基本。这包括清晰地分解代码，选择一目了然的变量名，以及插入注释来描述任何隐含的内容。

2、不要问你的 pull request 能为你的下一次推广做什么，而要问你的 pull request 能为用户和社区做什么。不惜一切代价避免 “引人注目的贡献”。如果这个功能对产品的目的没有明显的帮助，就不要添加任何功能。

3、品味也适用于代码。品味是一种约束 - 满足的过程，由对简单性的渴望所规范。保持对简单性的偏倚。

4、可以拒绝——仅仅因为有人要求某个功能并不意味着你就应该这么做。每个功能都有一个超出初始实现的成本：维护成本、文档成本和用户的认知成本。应该总是问：我们真的应该这样做吗？通常，答案是否定的。

5、当你对支持新用例的请求说 “是” 时，请记住，按字面意思添加用户请求的内容通常不是最佳选择。用户关注的是他们自己的特定用例，你必须以整个项目的整体视角和原则视角来应对这一点。通常，正确的答案是扩展现有的功能。

6、投资于持续集成，并以全面的单元测试覆盖为目标。确保你处在一个可以自信地编码的环境中；如果不是，那么就从构建正确的基础设施开始。

7、如果没有事先计划好一切，没关系。尝试一下，看看结果如何。尽早恢复错误的选择。确保创建了一个可行的环境。

8、好的软件能让困难的事情变简单。仅仅因为一开始问题看起来很困难，并不意味着解决方案必须很复杂或者很难使用。工程师们经常采用习惯性思维的解决方案，这种方案会带来不必要的复杂性和副作用（“让我们使用 ML 吧！让我们构建一个应用程序！让我们添加区块链！”)，或许还存在可能不那么明显，但是更容易的替代方案。在编写任何代码之前，请确保你所选择的解决方案是最简单的。从第一原则着手。

9、避免隐式规则。你自己开发的隐式规则应该始终是明确的，并与他人共享或能够自动化。当你发现自己提出了一个重复的、拟算法的工作流时，应该设法将它形式化为一个文档化的流程，以便其他团队成员能够从经验中获益。此外，你应该设法在软件中自动化任何可以自动化的工作流程（例如正确性检查）。

10、应该在设计过程中考虑你的选择的总体影响，而不仅仅考虑你想要关注的方面——比如收入或增长。除了正在监控的度量之外，你的软件对其用户、对世界的总体影响是什么？是否有超出其价值主张的副作用？在保持软件有用性的同时，你还能做些什么来解决这些问题？

关于 API 设计

1、你的 API 拥有用户，因此要考虑用户体验。在你所做的每一个决定中，始终牢记用户。对你的用户感同身受，无论他们是初学者还是经验丰富的开发人员。

2、始终追求尽量减少用户在使用 API 过程中的认知负担。自动化可以自动化的一切东西，最小化用户需要的操作和选择，不要显示不重要的选项，设计简单一致的工作流，反映简单一致的思维模型。

3、简单的事情应该是简单的，复杂的事情应该是可能的。不要为了小范围的用例而增加普通用例的认知负担，即使是最低限度的。

4、如果工作流的认知负载足够低，那么用户在完成一到两次工作之后，应该可以从记忆中遍历工作流（无需查找教程或文档）。

5、追求与领域专家和从业者的心理模型相匹配的 API。有领域经验但没有 API 经验的人应该能够使用最少的文档直观地理解你的 API，主要通过查看一些代码示例，看看哪些对象可用，以及它们的签名是什么。

6、一个参数的含义应该是可以理解的，而不需要任何与底层实现相关的上下文。必须由用户指定的参数应该与用户对该问题的心理模型相关，而不是与代码中的实现细节相关。一个 API 只关注它解决的问题，而不关心软件在后台如何工作。

7、最强大的心理模型是模块化和层次化的：在高层次上很简单，但在细节上很精确。同样，一个好的 API 是模块化和层次化的：易于上手，但富有表现力。一个好的 API 有合理数量的对象，有相当简单的签名。

8、你的 API 不可避免地反映了你的实现选择，特别是你对数据结构的选择。要实现直观的 API，必须选择自然适合手边领域的数据结构——与领域专家的心理模型相匹配。

9、设计端到端工作流，而不是一组基本特性。大多数开发人员通过询问 “应该提供哪些功能？让我们为它们提供配置选项。” 相反，要问 “这个工具的用例是什么？对于每个用例，用户操作的最佳顺序是什么？支持这个工作流的最简单的 API 是什么？”API 中的基本选项应该能够满足高层次工作流中出现的明显需求——不应该因为“可能有人需要” 而添加它们。

10、错误消息，以及在与 API 交互过程中向用户提供的任何反馈，都是 API 的一部分。交互性和反馈是用户体验的一部分。需要特意设计 API 的错误消息。

11、因为代码是一种沟通，命名很重要——无论是命名项目还是命名变量。名字反映了你对问题的看法。避免过于通用的名称（如 “x，变量，参数”），避免过于冗长和特殊的命名模式，避免可能造成不必要的分歧的术语（如“主 / 从”），并确保你的命名选择是一致的。命名一致性意味着内部命名一致性（例如，不要将在其他地方使用的“axis” 称为“dim”），以及与问题领域的既定约定的一致性。在确定名称之前，请确保查找领域专家（或其他 API）使用的现有名称。

12、文档是 API 用户体验的中心。它不是一个附加组件。投入于高质量的文档；这将比投入更多功能有更高的回报。

13、展示，而非解释：你的文档不应该讨论软件如何工作，而应该展示如何使用它。展示端到端工作流的代码示例；为 API 的每个常见用例和关键特性展示代码示例。

关于软件设计师的职业规划

1、职业发展不在于你管理了多少人，而在于你创造了多少影响。

2、软件开发是团队合作；它不仅关乎技术能力，也关乎人际关系。做一个好的队友。当你走在路上，要和别人保持联系。

3、技术从来都不是中立的。如果你的工作对世界有任何影响，那么这种影响就是有道德导向的。我们在软件产品中做出的看似无害的技术选择调整了技术获取的条件、使用动机、谁将受益、谁将受害：技术选择也是道德选择。因此，对于你希望你的选择支持的价值观，一定要慎重而明确。把你的价值观融入你的作品中。永远不要想 “我只是在构建功能；这本身是中立的”。它不是中立的，因为你构建它的方式决定了它将如何被使用。

4、自我导向——掌控你的工作和环境——是获得生活满足感的关键。确保你给你周围的人足够的自我导向，确保你的职业选择为你自己带来好处。

5、创造世界所需要的东西，而不仅仅是你自己希望拥有的东西。技术人员往往专注于满足资深特定需求的产品。寻找机会拓宽你的生活体验，这将帮助你更好地了解世界需要什么。

6、当做出任何具有长期影响的选择时，将你的价值观置于短期自我利益和短暂情绪之上——比如贪婪或恐惧。要知道你的价值观是什么，让它们来引导你。

7、当我们发现自己陷入冲突时，停下来确认我们共同的价值观和共同的目标是个好主意，并提醒自己，我们几乎肯定站在同一条战线上。

8、生产力可以归结为快速决策和行动偏好。这需要 a) 良好的直觉，这来自经验，以便在给出部分信息的情况下做出普遍正确的决定；b) 对何时更谨慎地移动和等待更多信息有敏锐的意识，因为一个错误决定的代价将大于延迟的代价。在不同的环境中，最佳速度 / 质量的决策权衡可能会有很大的差异。

9、更快地做出决策意味着你在职业生涯中要做出更多决策，这将使你对可用选项的正确性有更强的直觉。经验是提高生产力的关键，更高的生产力将为你提供更多的经验：良性循环。

10、在你意识到自己缺乏直觉的情况下，请遵守抽象原则。在整个职业生涯中建立一份可靠且实际的原则列表：原则是形式化的直觉，它适用于比原始模式识别更广泛的情境。