【CSDN编者按】：每个人在工作中，工作内容不同，得到的收获和教训也不同。而及时的总结，给自己反馈，则会在下一步的工作中得到印证。

原文链接：https://medium.com/better-programming/20-software-engineering-guidelines-i-learned-in-2020-8106d03d953b

编译 | 弯月    责编 | 丁恩华

头图 | CSDN 下载自视觉中国

出品 | CSDN（ID：CSDNnews）

2020 年是我正式成为软件工程师的第一年，也是我在旧金山度过的第一年。受疫情的影响，我没有太多机会去探索这座新城市，只能呆在家里练习烘培技术和刷剧。然而，事情也有好的一面，我有大量的时间宅在家里做自己的项目。这一年里，我学习了很多有关软件工程的最佳实践，在本文中，我将介绍我学习到的最有价值的20条准则。

提高代码的可读性

开发人员需要花费大量的时间阅读代码，甚至超过了编写代码的时间。这里我所说的阅读包括以下工作：调试代码、检查他人提交的代码、学习新的代码库等等。因此，你应该确保自己的代码便于阅读，即便有的时候你需要更长的命名、编写更多代码，以及舍弃自己的“小聪明”。

举个例子，虽然变量名 timeInMillis 比 time 更长，你需要输入的字符也更多，但是开发人员无需查看其他代码就能明白这个变量计算的是哪种时间。

再举一个例子，网上有很多一行代码的解决方案。例如，如下判断回文数的写法非常聪明（注：回文数指的是像 14641 这样“对称”的数，即：将这个数的数字按相反的顺序重新排列后，所得到的数和原来的数一样）：

def isPalindrome(self, x: int) -> bool:a=list(str(x))return a==a[::-1]

但是，非常难以理解。一行代码的解决方案很有挑战性，不建议在多人共同维护的代码库中采用这种写法。

重构的价值

只有当重构帮助你和团队成员节省的时间超过重构花费的时间，才值得投入。你应该将精力集中到频繁阅读和编写的代码上。

你可以考虑，将不紧急的重构分配给新来的团队成员练手，这样他们不但有机会学习，同时也能贡献价值。

将技术负债视作财务负债，可以适量承担一些

有时，从业务的角度出发，尽快提供有价值的功能可以获取更大利益，比如赶在竞争对手发布类似的功能之前，即使这个时候的功能还不够完美也没关系，只要你可以建立计划，赶在债台高筑，被“利息”压得透不过气来之前，及时地改善代码。如果技术负债的积累速度超过你的偿还能力，那么就会出现问题，代码库的处理难度就会越来越大。

例如，在时间紧迫的情况下，在完成测试之前就发布某项功能也可能是正确的业务决策，但是事后你需要立即补上测试。如果你拖延测试，很快这些未测试的代码之上就会出现新的代码，未经测试就发布的功能也会相继出现，那么偿还这部分技术负债的难度就会越来越大，很难再还给团队一个维护良好的代码库。

不要制造惊喜

团队成员会假定你的代码遵循常见的惯例，所以你不应该偏离这些惯例，不要给他们制造惊喜。

例如，如果你编写了一个函数 isButtonEnabled()，那么团队成员肯定会假定这个函数是在检查某个按钮，它会返回一个布尔值，因为绝大多数的这类函数名称都以“is-”开头。如果你的函数还做了其他处理，那么就应该在名称中澄清。

命名的长度应该视范围而定

例如，for 循环中可以使用 i 和 j 之类的变量名，但是全局常量的名称应该更加精准地表达它的意图。

函数也需要保证可读性，而不仅仅是为了避免重复

一般，我们常说重复三次以上的代码都应该写成函数，但我还想再加两点应该写成函数的情况：1）当需要添加注释解释这段代码的用途的时候；2）当嵌套超过3层的时候。

举个例子，假设我编写了下列UI函数：

fun setupViews() {
// set up textViewtextView.isVisible = …textView.text = ……more textView setup…
// set up imageViewimageView.image = …imageView.backgroundColor = ……more imageView setup…
}

我们应该将相应的代码分别放入另外两个函数 setupTextView() 和 setupImageView()，即便它们不包含重复代码。通过这种方式编写出来的代码，本身就可以作为文档，而且如果有人需要修改或调试 imageView，他可以直接去 setupImageView()，而无需阅读所有的代码。

另一个常见的情况是关于函数的最大代码行数，这个值的设置非常随意，通常在5～100的范围内。我个人认为基本的标准是：阅读函数的时候不需要翻页。

重复的呈现形式有很多种

DRY（Don't repeat yourself，不要重复你自己）是一个众所周知的软件工程原则。一般，最常见的重复就是完全相同的代码，但是也有一些重复的形式并没有那么明显，例如实现的重复。

举个例子，对于如下定义的类：

class TreeNode {val value: Stringvar children: List<TreeNode>val isLeaf: Booleanfun addChild(node: TreeNode) {children.add(node)isLeaf = false}fun removeChild(node: TreeNode) {children.remove(node)if (children.isEmpty()) isLeaf = true}
}

其实，你不需要在每次 child 更新的时候设置 isLeaf， 你可以添加 fun isLeaf() = children.isEmpty()，如此一来，在更新这个类的时候，你就无需检查 isLeaf 是否被更新了。

不要重复其他人的工作

在实现某个功能之前，首先你应该先检查一下代码库中是否已有现成的实现。

例如，你需要处理时间，常量 SECONDS_PER_MINUTE 可能已经存在了，你可以直接重用，而不应该在同一个代码库中多次定义这个常量。

学习并遵守项目的编程风格

一套统一的开发指南可以方便团队成员理解彼此的代码，也可以方便新来的成员。通常，实际的规则并不重要，重要的是你需要确保这些规则被贯彻执行了。例如，我曾见过一些 Kotlin，所有包含扩展函数的文件名都以“-Ext”结尾，而其他文件则使用“-s”结尾。实际的选择并不重要，重要的是所有人的选择必须统一，只有这样程序员才知道哪里能找到 Foo 的扩展函数，是在 FooExt.kt 中还是在 Foos.kt 中？

通过 lint 规则提升代码的整洁度

如果你在项目中使用了lint工具，而且你经常手动调整格式，或者在代码审核时经常有人提出格式方面的建议，那么就应该考虑一下增加一条新的lint规则。

学习使用 IDE

现代 IDE（比如Android Studio 和 VSCode）非常强大。你应该学习如何使用 IDE 的各种小工具（比如调试器），以及键盘快捷键，虽然这需要投入一定的时间，但从长远打算来看能够为你节省很多时间。

你应该自定义设置和键盘快捷键，优化你的工作流程。例如，JetBrains IDE 默认不提供“Split editor tab”的快捷键（你必须点击Window → Editor Tabs → Split Vertically），但是我添加了一个自定义的快捷键，因为我经常使用。

注释应该解释原因，而不是实现方式

理想情况下，代码应该不言自明，不需要添加注释。程序员在修改代码的时候，经常忽略更新注释，时间久了，注释就会不准确，与实际的代码大相径庭。在你打算写注释，解释代码的功能时，不妨考虑一下重构代码，让代码不言自明。

然而，仅靠代码自身还不足以解释为什么你选择这种方式。注释可以提供上下文，比如帮助你做出决策的产品需求、系统限制或出于效率的考虑。

不要将测试代码视作二等公民

在编写生产代码的时候，你可能需要花点时间计划代码，确保在功能发布之前达到良好的品质，但是程序员通常都会忽视测试代码，只要能正常运行就可以了。然而，测试代码也需要维护，如果这些代码很难理解，那么就会增加维护的负担。

部分问题是测试代码一般都不需要经过严格的审核。大家会花费大量时间审核生产代码，却觉得测试代码没这个必要，因为毕竟已经通过了测试。

表格驱动测试

几个月以前，我发现了Junit的参数化测试，这种方法帮助我编写了更多彻底的测试。

在常规单元测试中，通常每个输入只有一个测试函数。最后会导致很多函数都有重复的代码，而且很容易漏掉一些输入。表格驱动测试有一个单独的测试函数，还有一个表格囊括了所有可能的输入以及预想的输出，只需要一个测试函数，就可以测试所有输入。

采用新库有风险

每个库都有预发布的版本，很有可能会破坏已有的功能。

在新发布的库中，易于测试可能是次要考虑因素，如果你想在大型项目中采用新库，事先必须验证这些库是否能够通过你的测试代码，并兼容生产代码。

在社区广泛采纳某个库之前，遇到问题时，很难找到资源。而且可能这个库永远也不会被广泛采纳，项目本身也会被维护人员遗忘。

对于有些库，看似每个人都在使用，但是真正的项目中采用了这些库吗？还是说只是出现在演示程序中？

向团队成员寻求帮助时，应该注意他们的方法，而不只是解决方案

注意团队成员使用的资源和工具，如果将来再遇到类似的问题，你能够更好地武装自己，靠自己的力量解决问题。发现新的资源和工具都很有价值，比如文档资源、Git命令、键盘快捷键等。

审核人员对代码变更感到不解或产生误解，则说明代码有问题

除了回应审核意见之外，你应该考虑重构或添加注释来澄清。这样可以确保将来其他人阅读这段代码的时候，不会遇到同样的困惑。

阅读代码审核意见

当你在理解某段代码时遇到困难，则应该仔细阅读代码的审核意见。从代码的审核意见可以看出，同时间内还有哪些代码发生了变化，因此阅读这些审核意见很有价值，而且其中还可能包含代码背后的决策说明。

如果你正在实现的某个功能与某个已有的功能非常相似，那么阅读相似功能的代码审核意见，可以帮助你规划自己的实现。例如，如果我想添加某个Android 功能，但iOS或Web已有这个功能，则看看其他平台的实现方法会有很有帮助性。

按照自己喜欢的方式学习

上大学的时候，除了课堂上的学习之外，你的知识主要来自自己的业余项目，在找工作的时候，这些经验会帮助你脱颖而出。但是，在之后的工作中，如果你想跳槽，则与自己的业余项目相比，实际工作项目的经验更能赢得面试官的青睐。

在业余项目中，你可以做自己喜欢做的事情，当然你可以继续享受这些项目！但是，除此之外，还有很多其他的学习方式：阅读博客、看演讲、参加在线课程、听播客等等。你可以找到自己最喜欢的方式，或者你也可以利用工作之外的时间发展其他兴趣爱好。

在线资源的质量层次不齐

任何人都可以通过互联网发表技术博客文章。如果你打算通过某篇博客文章学习新技术，却发现其中的内容不太合理，那么可能只是因为文章本身写的不怎样，你不必就此放弃，而是应该尝试其他资源。

官方的资源和教程通常都是很好的切入点。会议演讲以及公司的技术博客的质量一般也都比较高，因为这些资源都经过了严格的审查。

最后

说到学习资源，以下是我常去的一些网站，本文提及的很多准则也正是来自这些资源：

• Refactoring Guru：一个网站，介绍了如何编写和重构整洁的代码。

• Clean Code：经典的软件工程书籍。有些内容有点过时，而且还与Refactoring Guru有重叠，但是仍然值得一读。

• Martin Fowler’s website：作者撰写了很多有关软件开发的书籍，而且他的网站也有很多关于软件架构与重构的信息。

• Android Weekly newsletter：一份周刊，精选了很多技术文章、播客以及演讲。仅限于Android，但是其他平台也有类似的周刊。

• Yelp Android school：科技演讲GitHub存储库。有一半是Android为主，还有一半讨论的是软件工程。

程序员如何避免陷入“内卷”、选择什么技术最有前景，中国开发者现状与技术趋势究竟是什么样？快来参与「2020 中国开发者大调查」，更有丰富奖品送不停！