`
阅读更多
!我知道大家都很忙,忙的连写注释和文档的时间都没有,更不要说做总结了。所以我就写一些短文,帮助大家总结一下。正如大家所知道的,我们的团队每天所面对的问题有很多——需求、测试、编码、变更、架构 …… ,好吧,就让我们从编码开始吧。
为什么要编码?

软件就是把人们的需要转化为计算机可以执行的程序。

这一点毫无疑问,但是这就是我们编码的目的吗?我们都知道,计算机其实很笨,它只能认识 0 和 1 这两个数字,无论多么复杂的程序都是由这两个最简单的数字构成。这正如哥德巴赫猜想,作为最复杂的数学证明题,要求解决的却是最简单的 1+1 问题。也就是说,最直接的编程就是向计算机输入 0 或者 1 ,为什么我们不这样呢?

原因当然很简单,因为 0 和 1 组成的机器语言实在是太难以理解和记忆了。于是前辈们就发明了汇编语言,汇编语言用单词代替了机器语言,它能够让人们更加容易理解代码和程序。可是前辈们又发现汇编语言还是太晦涩难懂,几百行代码已经让人云山雾罩,遇到几万行的大型程序,那简直就是天书了。所以先行者们又发明了高级语言,高级语言用接近自然语言的方式来编写程序,就象自然语言一样,它(们)成为了程序员阐明观点交流思想的通用工具。

所以,我们编写代码的目的就是为了交流和沟通,而这,也正是计算机语言存在的意义。
考虑别人

既然编写代码的目的是为了沟通,那么作为一个程序员有什么理由去写那些只有自己才能够看懂的代码呢。如果吧这个作为一个问题问大家,恐怕没有一个人会这样回答:“编写只有自己能看懂的代码,让别人去猜吧!”。因为大家都希望合作,都愿意与其他人沟通,这不仅仅是工作的需要也是人类的基本需要之一。

可是,并不是每一个程序员都懂得沟通的艺术。几年前,我认识了一个很有天分的程序员,他的编程能力让人吃惊。但是,当他把一个命名为“ tj ”的函数交给我的时候,我只有无语了——“统计?”“添加?”,反复猜测不得要领之后,我只好让他重写这个函数。这样的例子还有很多,几乎每一个新手都出现过这样问题,即使他们对所使用的编程语言掌握的无比纯熟。

那么怎样才能编写一份能够阅读并易于理解的代码呢?下面我给出一些建议,其中的一些已经作为我们团队《编程规范》的一部分而被大家了解了,而另一些则不然。

●      时刻考虑你所编写的每一行代码、代码中的每一个单词都会在将来某个时候被你的伙伴们阅读、测试和维护。这是一个原则,也是一个前提,是每一个程序员所必须具备的基本素质。在一个团队中,编写可以阅读和维护的代码是团队合作的前提条件。

●    必须认真的慎重的为你的变量、函数(方法)、类命名。要起一个科学合理的名字,因为名字是理解代码的重要依据。同时,一旦代码发布,其依赖者、继承者都要永远维持这种命名。想像一下,如果你和你的同事不得不使用类似“ tj ”这样的名字,而又不能改变现状(会影响其他使用者),那该是一件多么痛苦的事情。

● 为你的代码编写注释。注释是代码的重要组成部分,同时也是别人理解你代码的重要依据,无论任务多么繁重,时间多么紧张,都应该象对待代码一样对待你的注释。哦,还有,最重要的是维护你的代码的同时要维护注释,就像下面一条所说的:

●  请确保注释是有效的。无效的,甚至是错误的注释还不如不写注释,这是显而易见的。注释应该言简意赅,不要用注释重复你的代码,也不要用注释阐述代码中显而易见的逻辑。请原谅我的啰嗦——在维护代码的同时不要忘记维护注释。

●   空行、空格也是代码。空行是一个逻辑段起止的标志,它和编程者的思路是一致的。另外,适当的使用空行和空格可以使你的代码更加清晰。

●   不要耍小聪明。只要有可能,请尽量使用平实的思路来规划你的代码。我们都知道,阅读别人的代码往往比自己编写同样功能的代码要困难,因为阅读代码的过程就是读懂对方思想的过程。困难的原因之一是作者的水平比读者要高——这当然是读者所欢迎的;但是,也可能是因为作者使用了晦涩难懂的思路和技巧,这些技巧五花八门无法列举,下面是常见的几种情况:

1)        过度的使用了设计模式。
这是设计模式初学者经常犯的错误,设计模式是面向对象思想的精华,但是对于经验较少的程序员来说,设计模式是抽象的和复杂的,过多的使用设计模式,会使得代码结构复杂难以理解。

2)        拼凑结果。
例如,某个复杂的函数返回的值总是比预期结果少 1 ,有些程序员会采用 +1 的方式使结果正确。这类做法往往使得代码逻辑混乱莫名其妙,更为严重的是,类似的方法很冗余导致程序中隐藏着错误。

3)        过度封装。
经常遇到的一种情况就是对第三方类库的进一步封装,这必须在有经验的设计者的指导下进行,因为类似的需求往往出现在各种架构级别的模块中。对第三方类库的不合理封装会导致使用着对类库的使用产生异议,出现错误的用法等。

4)        拒绝使用成熟的第三方类库。
许多初级设计人员,往往喜欢自己编写框架级别的代码,例如,在 JavaEE 开发中自行设计 MVC 框架。这类做法在多数情况下都是错误的,因为成熟的产品比比皆是,这些产品都有广泛的用户群、详尽的文档、活跃的社区和大量的成熟案例。普通开发人员极少能够自行编写同样水准的代码,而且,即便写出来了谁又能够保证其他开发人员会使用并且喜欢使用呢。

5)        冒然采用新的技术。
程序员是思维活跃敢于尝试创新的人群,他们往往乐于使用新的技术和新的产品。但是,在使用这些产品之前请仔细考虑:“你了解它吗 ? ”。冒然在团队中应用新技术是一种非常不负责任的行为,学习曲线、隐藏 BUG 、适用范围等等会成为应用新技术的障碍,严重的情况下一个类似的决策会导致整个项目的失败。


消除重复

如果说软件目的就是将需求转换为程序,那么软件的本质就是复用。复用是一个非常宽泛概念,微软将 Windows 操作系统刻录成光盘出售,用户买到的都是同样的程序,这就是复用;我们使用 163 或者 google 的 Email 服务,访问同样的 Web 网站,这,也是复用。一个程序、一个 URL 、一个架构、一个类、一个方法都可以成为复用的对象。这里,我们只讨论代码的复用。

● 仅在需要的时候使用接口。
接口为我们的应用提供很好的“可替换性”,简单的说,使用者仅依赖接口,而不必考虑接口是如何实现的,这样,一旦发生变化只需要重新实现接口,而依赖于接口的代码不必改动。显然,接口是非常强大的,它使得我们的代码具有扩展性,但是,是否所有的模块都需要这种扩展性呢?实践证明, 80% 左右的模块不需要替换实现类,这些模块即使发生了变化也往往是局部的,不会影响其他模块。而对它们的修改和维护的工作量要远远小于重新实现它们的接口。这类模块,是不需要接口的。那么什么时候使用接口呢,下面列出几种常见的情况:

1)  两个并行开发的模块(或类、子系统),互相存在依赖关系。
例如, A 模块依赖 B 模块的某些功能,因为是并行开发的,所以 B 模块可能还没有完成,这个时候,需要 B 模块提供接口以供 A 模块使用。 A 模块开发的时候,可以先使用一个 B 模块接口的“模拟实现”,等到 B 模块完成,再替换为真实的实现。

2)  对于结构复杂的或提供公共服务的模块。
有时候,需要提供一些公共的服务为整个系统使用。例如,在 Java 中直接使用 JDBC 操作数据库往往比较繁琐,这个使用需要提供一个通用的 JDBC 封装,将重复繁琐的 JDBC 操作提取到抽象类或者工具类中。但是, JDBC 操作中并非所有的代码都是重复的和可预见的,此时应该将这些非重复的和不可预见的代码抽象为接口,工具类依赖接口编程,工具类的使用者来根据自身情况实现这些接口。这其实是一个策略模式的应用,在实际开发中是很常见的。

3)  当模块的可变性是可以预见的时候。
如果开发人员预见到:“这个模块将来一定会发生某种变化”,那么此时可以使用接口。这种情况下,接口的粒度一定要细,仅仅包含变化的功能即可。例如,一组结构相同的数据,需要我们对其中一些特殊的数据进行处理,而原始数据中并没有提供某种规律来辨别哪些数据是特殊的,此时,我们只好通过硬编码( Hard Code )来处理这些特殊数据(例如,通过名称来判断)。这显然是代码中的坏味道,解决的办法就是提供一个用于判别特殊性的接口,然后用 Hard Code 的部分来实现接口,当客户方提供了数据的规律的时候,重新实现一个就可以了。

4)  在某些大型项目中,不同的模块可能需要不同的团队甚至不同公司进行开发。这个时候需要使用接口来规范双方之间的通信。



● 用抽象类实现公用的代码。
面向对象的原则告诉我们,聚合复用应该优先于继承复用。但是,当你确定某些类从本质上讲是同一个类别 的时候,就应该考虑将这些类的公共部分提取到抽象类中,以实现代码的复用。经过这种处理的子类比原来要精简很多,甚至比使用了聚合复用还要精简。

● 在复杂的模块中使用设计模式。

● 适量的使用条件分支判断。
大量的条件分支判断会导致代码冗长、结构松散、逻辑混乱,这类代码往往没有可阅读性和可维护性。但是,并非 if-else 就不能使用的了,只要遵循下面的原则, if-else 仍然可以使用:

1)      一组条件分支只判断一类条件。多种条件混合在一组分支中只能说明编程者的思维混乱。

2)      分支要尽可能少,不要超过 8 个。

3)      每个分支的代码在 3 行以内。

4)      每个分支都有注释。

5)      最后一个分支用于判断缺省情况。

6)      如果上述 5 条不能同时满足,请休息片刻,然后重构你的代码。

● 不要 Copy-Paste 你的代码。
当你 Copy-Paste 代码的时候,说明代码中存在重复,重复的代码往往导致代码难以维护和阅读。一旦那些保存在剪切板中的代码中存在错误,编写者甚至不知道到哪里修改这些错误。每当你 Copy-Paste 代码的时候,请停下来,考虑将这些代码提取为方法、类或者组件。
源代码就是文档

我们为什么写设计文档呢?设计文档可以说明你的代码,阐明设计思路,文档是我们沟通的重要工具,它可以使软件具有可持续发展性。这里我只想说说详细设计文档。 几年 前,我一直有一些疑问,什么是概要设计和详细设计?怎样才算“概要”?怎样才算“详细”?详细到什么程度才算合格?

现在我已经明白了,所谓概要设计就是架构设计,架构就是将一个软件中功能性的东西剔除之后剩下的部分。这一部分是软件的结构,它说明了软件中最为重要的特性和这些特性的实现方式。

那么详细设计呢?我曾经看到过的详细设计可以细致到伪代码,程序员可以不必动脑筋,直接将伪代码翻译为 Java 或者 C# 代码即可。我对这样的设计人员致以无比的敬意,因为他(们)不但可以为数量远超他们的程序员写代码,更为神奇的是,这些代码可以在没有调试过的情况下正常运行。但是,我想今生我都无法达到这个水平了。而且即使我达到了这个水平,我还要为这些设计文档的维护尤其是文档与代码之间的同步 付出无比艰辛的劳动,与其这样,我不如:



●         简单设计。
Kent Beck 在《解析极限编程——拥抱变化》中为简单设计制定了 4 个评价标准,依次为(最重要的排在最前面):通过所有测试;体现所有意图;避免重复;类或者方法数量最少。这其中包含的核心意义就是不要为了考虑程序的可扩展性,把目前不需要的功能加入到软件中来。不要为了遵循某种规范而编写大量无用的甚至是起到反作用的文档,将精力转移到代码上来。依附在良好架构上的优质代码,比任何文档的作用都明显。

●         单元测试的文档作用。
测试方面我将另行撰文阐述,这里所说的是单元测试的文档作用。任何一个学习计算机编程的人都知道, 10 行文字说明不如一行代码演示,这体现了“例子”的重要性。单元测试对于维护者而言就是“例子”,当维护者难以理解你的代码,当使用者不知如何使用你写的 API ,当你自己不知道修改代码会造成哪些影响的时候,单元测试可以为你说明一切。所以,请每一个程序员都要认真的编写测试代码,力求测试代码能够反映全部的意图,此时,单元测试就是文档!它不但能够说明代码的使用、功能,而且天然的与代码同步,更重要的是,它可以使你放心的维护你的代码。

●         现代编程语言对于文档的支持。
在 Java 、 C# 、 Ruby 等新兴的编程语言中,可以将代码注释当作文档使用。例如 Java 为文档提供了很多支持——使用 HTML 标签、使用 @ 标记等,结合 Javadoc 命令就可以生成 HTML 格式的文档。相比传统的 Word 文档,注释作为文档的优势是显而易见的:

1)  天然的与代码同步,省去了很多同步的成本。

2)  连接特性使得文档更容易阅读。

3)  更加规范的文档格式。

●         源码之前了无秘密。
当测试、注释、文档都失去作用的时候,不要忘记,我们还有逻辑,还有代码!代码之前了无秘密。优质的代码是说明应用程序的最根本的方式,是程序员沟通的通用语言。
所以,请认真的编写每一行代码!
分享到:
评论

相关推荐

    小团队构建大网站:中小研发团队架构实践(高清完整版)

    《小团队构建大网站:中小研发团队架构实践》是一本专为中小型开发团队设计的指导书籍,旨在帮助这些团队在有限的资源下高效地构建和维护大规模的网站。书中涵盖了从项目规划、技术选型、架构设计到团队协作等多个...

    极客与团队

    《极客与团队》是一本写给程序员看的,教你怎么交朋友,怎么影响团队中的其他人。书中充满了操作性极强的建议和意见,让你在技术团队中过得更开心,变得更有效率,更加如鱼得水。本书旨在帮助程序员改进理解他人,与...

    团队精神评语怎么写 .doc

    以下是从给出的文档内容中提炼出的相关知识点: 1. **高效协作**:优秀的团队能够在面对压力和多重任务时,通过强化内部管理,使每个成员明确职责,确保团队通力合作,按时完成任务。例如,经营部在任务量巨大的...

    设计团队CSS网页模板

    "设计团队CSS网页模板"是专为设计团队、企业和商业机构打造的一款专业网页设计方案,它采用了黑色调,营造出一种商务且专业的氛围,同时也展现了设计团队的独特风格和创意。 CSS(层叠样式表)是网页设计的核心技术...

    设计团队css+div网页模板

    总的来说,这个"设计团队css+div网页模板"是一个实用的工具,可以帮助设计团队快速搭建出专业级别的网站。通过熟练运用CSS和div元素,设计师可以创造出适应性强、交互性好、视觉效果出众的网页,提升用户在网站上的...

    开发团队调度系统.zip

    这个系统的主要任务是:从已经给定的公司员工的列表中,选择一定数目(设定的是5人)的员工,加入到 软件开发团队中。 其中,公司的员工股分为不同的种类:employee(普通员工)、programmer(程序员)、designer...

    基于PHP科研团队管理系统.zip

    在科研团队管理系统中,MySQL用于存储和管理团队成员信息、项目详情、任务分配、进度记录等大量数据。通过SQL语句,开发者可以方便地进行数据查询、更新和管理。 3. **科研团队管理**:科研团队管理涉及到人员配置...

    【心得体会】团队建设心得体会怎么写【四篇】.doc

    在实际操作中,团队建设活动可以多样化,如团队讨论、团队游戏、户外拓展训练等,这些活动可以帮助团队成员建立信任,增强团队协作能力,同时也能在轻松的氛围中增进团队成员之间的了解和友谊。 总的来说,团队建设...

    开发团队中的文档编写者

    文档编写在IT行业中扮演着至关重要的角色,因为它确保了团队之间的有效沟通,用户理解软件产品的正确方式,以及软件开发过程的规范性。作为开发团队的文档编写者,你需要掌握一系列关键技能和方法来创建高质量的技术...

    团队执行力培训学习总结多篇_写总结.pdf

    【团队执行力】团队执行力是指团队成员能够有效地执行战略计划,高效协同完成工作任务的能力。团队执行力的高低直接影响到团队的整体效率和工作质量。在团队中,每个成员的角色和贡献都至关重要,如同木桶原理,团队...

    写好Hive程序的五个提示,淘宝数据平台团队

    标题中提到的“写好Hive程序的五个提示”指向了在大数据领域内使用Hive语言编写的程序优化和最佳实践。Hive作为一个建立在Hadoop之上的数据仓库工具,可以将SQL语句转换为MapReduce任务进行执行,非常适合处理大数据...

    好看的团队介绍源码.zip

    这些样式可能直接写在HTML文件内部(内联样式),或者放在外部CSS文件中(例如,`style.css`),并通过`<link>`标签引入。 此外,考虑到页面的响应性,源码可能还应用了媒体查询(Media Queries)来确保页面在不同...

    跟我一起写 Makefile.zip资料vasp密度泛函DFT模拟计算态资料文档下载

    跟我一起写 Makefile.zip资料vasp密度泛函DFT模拟计算态资料文档下载跟我一起写 Makefile.zip资料vasp密度泛函DFT模拟计算态资料文档下载跟我一起写 Makefile.zip资料vasp密度泛函DFT模拟计算态资料文档下载跟我一起...

    军训总结写给教官5篇.docx

    【标题】和【描述】中提到的"军训总结写给教官"主要指的是大学新生在军训结束后,对军训经历的回顾和对教官的感激之情的表达。虽然文档的标签为"技术",但实际内容更偏向于个人成长和团队建设,因此在这里,我们将...

    Atom-teletype,与团队成员共享工作空间,并在atom-atom/teletype中实时协作编写代码.zip

    然后,创建或加入一个工作空间,分享工作区的唯一标识符(通常是哈希值)给你的团队成员。他们只需在自己的Atom中输入该标识符,就能连接到共享的工作区。 在实际项目中,Atom-teletype可以帮助团队提高生产力,...

    广联达全国五代写锁工具

    总的来说,广联达全国五代写锁工具是建设行业信息化解决方案的重要组成部分,它通过强大的数据保护和协同工作管理,提升了团队协作效率,保障了工程项目的顺利进行。对于大型项目团队而言,选择这样一款专业工具,...

    广联达写锁工具

    总的来说,广联达写锁工具是GFY2012精细化管理软件的重要补充,它提升了团队协作的效率,降低了数据风险,是大型项目预算管理不可或缺的一部分。通过合理使用,可以极大地提高工作效率,保证预算工作的准确性和稳定...

    2023新UI大气好看的个人团队简介主页源码 带后台.zip

    2023新UI大气好看的个人团队简介主页源码 带后台 源码说明 1.把源码上传到服务器 2.php版本设置7.2,估摸着好像都可以的,我开发的时候用的7.2 3.导入数据库,idcmba.sql 4.前往源码根目录设置数据库账号密码/...

    golangc乱写了一个基于http的垃圾远控支持团队协同作.zip

    golangc乱写了一个基于http的垃圾远控支持团队协同作

Global site tag (gtag.js) - Google Analytics