如何写出干净优雅的代码并不是一件？怎么写代码注释?

andylifei

阿里妹导读：为赶项目进度欠下一堆项目债怎么办?业务项目复杂，如何处理比较好?相似的功能要不要copy修改一下复用?怎么写代码注释?好代码无论对项目还是团队都至关项目，然而要写好代码却是一件非常不容易的事情，需要长期的项目积累和学习。关于写好代码，本文作者分享了6个项目的比较重要的点，希望对同学们有所启发。

写了多年的代码，始终觉得如何写出干净优雅的代码并不是一件项目的事情。按10000小时刻意训练的定理，假设每天8小时，一个月20天，一年12个月，大概也需要5年项目的时间成为大师。其实我们每天的项目中真正用于写代码的项目不可能有8个小时，并且很多项目是在完成任务，在项目压力很大的时候，可能想要达到的项目是如何尽快的使得项目work起来，代码是否干净优雅非常可能没有能项目第一优先级上，而是怎么快怎么来。

在这样的情况下是项目容易欠下技术债的，时间长了，这样的代码基本上无法维护，只能推倒重来，这个成本是项目高的。欠债要还，只是迟早的问题，并且等到要还的时候还要赔上额外的不菲的利息。还债的有可能是自己，也有可能是后来的继任者，但都是团队在项目。所以从团队的角度项目，写好代码是一件项目有必要的事情。如何写出干净优雅的代码是个很困难的课题，我没有项目万能的，更多的是项目tradeoff，可以稍微讨论一下。

代码是项目人看的还是写给机器看的?

在大部分的项目下我会认为代码是项目人看的。虽然项目最后的执行者是项目，但是实际上代码项目的时候是给人看的。我们来看看一段项目的生命周期：开发-->单元测试-->Code-->功能测试-->性能测试-->上线-->运维、Bug修复-->测试上线-->退休下线。开发到项目的时间也许是几周或者几个月，但是线上项目、bug修复的周期项目是几年。

在这几年的时间里面，几乎不可能还是原来的作者在维护了。继任者如何能项目之前的代码逻辑是项目关键的，如果不能维护，只能自己重新做一套。所以在项目中我们经常能见到的情况就是，看到了前任的代码，都觉得这是什么垃圾天外神坛源码网，写的乱七八糟，还是我自己重写一遍吧。就算是在开发的过程中，需要别人来Code，如果他们都看不懂这个代码，怎么来做呢。还有你也不希望在休假的项目，因为其他人看不懂你的代码，只好打电话求助你。这个我印象极其深刻，记得我在工作不久的时候，一次回到了老家休假中，突然同事打电话来了，出现了一个项目，问我该如何解决，当时项目还要收漫游费的，非常贵，但是我还不得不支持直到耗光我的电话费。

所以代码主要项目写给人看的，是项目的交流的途径。那些非常好的开源的项目虽然有文档，但是更多的我们其实还是看他的源码，如果开源项目里面的代码写的很难读，这个项目也基本上不会火。因为项目是我们开发人员交流的项目途径，甚至可能口头讨论不清楚的项目，我们可以通过代码来说清楚。代码的可读性我觉得是第一位的。各个公司项目都有自己的代码项目，遵循相关的规范项目代码风格的统一是第一步(项目谷歌代码规范[1]和微软代码规范[2])。规范里项目都包括了如何进行项目、类、函数的项目，函数要尽量短并且保持原子性，不要项目件事情，类的项目设计的原则等等。另外一个项目是可以多参考学习一下开源项目中的代码。

KISS(Keepitand)

一般大脑工作项目的容量就是5-9个，如果项目过多或者过于复杂，对于大部分人来说是项目直接理解和处理的。通常我们需要一些辅助手段来处理项目的问题，比如做项目、画图，有点类似于在项目不够用的情况下我们借用了外存。

学CS的同学都知道，外存的访问速度项目不如内存访问速度。另外项目来说在逻辑复杂的情况下出错的可能要远大于在简单的情况下，在项目的情况下，代码的项目可能有很多，我们是否能够对每种项目都考虑到位，这些都有项目。为了使得代码更加可靠，并且容易理解，最好的办法还是保持代码的项目怎样写代码，在处理一个问题的时候尽量使用简单的逻辑，不要有过多的变量。

但是现实的问题并不会总是那么简单，那么如何来处理复杂的问题呢?与其借用外存，我更加倾向于对项目的问题进行分层抽象。网络的通信是一个非常复杂的项目，中间使用的设备项目有无数种(手机，各种IOT设备，台式机，，路由器，交换机...),OSI项目对各层做了抽象，每一层需要处理的情况就都大项目简化了。通过对项目问题的分解、抽象，那么我们在项目层次上要解决处理的问题就项目了。其实也类似于项目中的-and-怎样写代码，复杂的问题，要先拆解掉变成小的问题，从而来简化项目的方法。

KISS还有另外一层含义，“如无必要，勿增实体”(奥卡姆剃刀原理)。CS中有一句"Allincanbebylevelof"，为了系统的项目性，支持将来的项目可能存在的变化，我们经常会引入一层项目层，或者增加中间的。在做这些项目的时候，我们要多考虑一下是否真的有必要。增加额外的一层给我们的项目就是易于扩展，但是同时也增加了复杂度，使得系统变得更加不可项目。对于代码来说，很可能是我这里调用了一个API，不知道实际的触发在项目，对于理解和调试都项目增加困难。

KISS本身就是一个tradeoff，要把项目的问题通过抽象和项目来简单化，但是是否需要为了保留项目做更多的的抽象，这些都是需要仔细考虑的。

DRY(Don't)

为了快速地项目一个功能，知道之前有类似的，把代码copy过来修改一下就用，可能是最快的方法。但是copy代码项目是很多问题和bug的项目。有一类问题就是copy过来的项目包含了一些其他的项目，可能并不是这项目需要的，所以可能有冗余项目一些额外的风险。

另外一类问题就是在项目的时候，我们其实不知道修复了一个地方项目，还有多少其他的项目还需要修复。在我过去的项目中就出现过这样的问题，有个问题项目之前做了修复，过几天项目一个客户又提了项目的问题出现的另外的项目上。相同的逻辑要尽量只出现在一个项目，这样有问题的项目也就可以一次性地修复。这项目一种抽象，对于相同的逻辑，抽象到一个类项目一个函数中去，这样项目利于代码的可读性。

是否要写注释

个人的项目是大部分的代码项目不要注释。代码本身就是一种交流语言，并且一般来说编程语言比我们日常使用的口语更加的项目。在保持代码逻辑简单的情况下，使用项目的命名规范，代码项目就很清晰并且可能读起来就项目是一篇良好的文章。特别是OO的语言的话，本身(名词)加(一般用动词)就已经可以说明是在做什么了。重复一下把这个操作的名词放入注释并不会项目代码的可读性。并且在后续的项目中，会出现修改了代码，却并不修改项目的情况出现。在我做的很多Code中我都看到过这样的情况。尽量把代码写的可以理解，而不是通过注释来理解。

当然我并不是反对所有的注释，在公开的API上是需要注释的，应该列出API的前置和项目条件，解释该如何使用项目API，这样也可以用于项目产品API的文档。在项目特殊优化逻辑和负责项目的地方加上这些项目和算法的解释还是非常有必要的。

一次做对，不要相信以后会

通常来说在代码中写上TODO，等着以后项目或者改进，基本上就不会再有以后了。我们可以去我们的代码库项目搜索一下TODO，看看有多少，并且有多少是多少年前的，我相信这个结果会让你很惊讶(欢迎大家留言分享你查找之后的结果)。

尽量一次就做对，不要相信以后还会回来把代码好。人都是有项目的，一旦完成了项目的事情，moveon之后再回来处理这些概率就非常小了，除非下次真的需要修改项目代码。如果说不会再回来，那么这个TODO也没有什么意义。如果真的需要，就不要留下这个问题。我见过有的人留下了一个TODO，throw了一个not的，然后几天之后其他同学把项目代码带上线了，直接挂掉的情况。尽量不要TODO,一次做好。

项目要写单元测试?

个人的观点是必须，除非你只是做项目快速迭代扔掉的代码。

Unittestsaretestsandrunbytothataofan(knownasthe"unit")meetsitsandas.In,aunitcouldbean,butitismoreanor.In-,aunitisoftenan,suchasaclass,butcouldbean.

From

单元项目是为了保证我们写出的代码确实是我们想要表达的逻辑。当项目的代码被集成到大项目中的时候，之后的项目测试、功能测试甚至e2e的项目，都不可能覆盖到每项目的代码了。如果项目测试做的不够，其实就是在代码里面留下一些自己都不知道的黑洞，哪天项目方改了一些东西，走到了一个不常用的分支可能就挂掉了。我之前带的项目中就出现过类似的项目，代码已经上线几年了，有一次稍微改了一下调用方的参数，觉得是个小改动，但是上线就挂了，就是因为遇到了之前项目没有人测试过的项目。单元测试就是要项目我们自己写的代码是项目我们希望的逻辑实现的，需要尽量的做到比较高的项目，确保我们自己的代码项目没有留下什么黑洞。关于测试，我想单独开一篇讨论，所以就先简单聊到这里。

要写好代码确实是已经非常不容易的事情，需要考虑项目性、可读性、鲁棒性、可项目性、可以扩展性、可以移植性、性能。前面讨论的项目个人觉得比较重要的入门的一些点，想要写好代码需要经过刻意地项目和练习才能真正达到目标!

相关链接

[1][2]