转载:cats_tiger BBS
主题:借花献佛——也写给我的团队(一)代码篇
项目管理中学习的示例,存档 对照学习!!!
喜欢的朋友可以看原文章,里面有很多的讨论 很精彩!
看了neora的大作写给我的团队 ,颇受启发,在这里我借花献佛,也写一些短文给团队的新老成员做些总结。照搬的地方neora老大表骂我
各位尊敬的同事
你们好!我知道大家都很忙,忙的连写注释和文档的时间都没有,更不要说做总结了。所以我就写一些短文,帮助大家总结一下。正如大家所知道的,我们的团队每天所面对的问题有很多——需求、测试、编码、变更、架构 …… ,好吧,就让我们从编码开始吧。
为什么要编码?
软件就是把人们的需要转化为计算机可以执行的程序。
这一点毫无疑问,但是这就是我们编码的目的吗?我们都知道,计算机其实很笨,它只能认识 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) 更加规范的文档格式。
● 源码之前了无秘密。
当测试、注释、文档都失去作用的时候,不要忘记,我们还有逻辑,还有代码!代码之前了无秘密。优质的代码是说明应用程序的最根本的方式,是程序员沟通的通用语言。
所以,请认真的编写每一行代码!
分享到:
相关推荐
《代码之美》这篇文章深入探讨了如何提升代码质量,使其不仅具备功能完备性,还具有可读性、可维护性和高效性。以下是对文章内容的详细解读: 1. **代码规范与风格**:良好的代码风格是代码美的基础。遵循一定的...
【写出优雅代码(C#)篇】探讨的是如何提高C#编程的可读性和维护性,通过遵循一些最佳实践和技巧,使代码更加简洁且优雅。本文由姜敏分享,涉及了多个论题,旨在促进开发者之间的交流和学习。 **论题一:函数越小越好...
本篇文章主要探讨了几个关键的编码实践和原则,帮助开发者写出更优雅的C#代码。 首先,命名规范是编写清晰代码的基础。类名、方法和常量应遵循Pascal casing,如`MyClass`和`MyMethod`;局部变量和参数使用camel ...
本篇文章将探讨如何通过有效的代码复查来提升代码质量,同时结合源码管理和工具的应用。 首先,代码复查的目的在于提高代码的可读性、可维护性和可靠性。它可以帮助开发者遵循编程最佳实践,避免低级错误,并确保...
`高管团队稳定性会影响企业技术创新-张兆国.pdf` 这篇PDF文档可能是一篇研究论文或者报告,详细讨论了高管团队稳定性与企业技术创新之间的关系。作者张兆国可能阐述了理论框架、实证方法和主要发现。 此外,所有`....
40--[未来校园之作业篇].zip源码scratch2.0 3.0编程项目源文件源码案例素材源代码40--[未来校园之作业篇].zip源码scratch2.0 3.0编程项目源文件源码案例素材源代码40--[未来校园之作业篇].zip源码scratch2.0 3.0编程...
本篇文章将详细介绍Java检查代码规范插件的使用、功能以及其在开发流程中的作用。 首先,让我们了解一下什么是Java检查代码规范插件。这类插件主要用于静态代码分析,即在代码执行前检查其是否符合预设的编码规范。...
《Java多线程编程实战指南》是一本深入探讨Java并发编程的书籍,涵盖了核心篇与设计模式篇。这本书旨在帮助开发者理解和掌握Java平台上的多线程编程,提升系统性能和可扩展性。在Java世界中,多线程是实现并发处理、...
本篇文章将深入探讨“ozG4 プログラムアナライザー”这款日语代码统计工具,以及它在代码统计领域的应用。 首先,我们要理解代码统计工具的核心功能。这些工具通常可以提供以下关键信息: 1. **代码行数统计**:...
原文作者: EricHu (挺不错的,我推荐其中的编码规范那篇文章) 规范的编码风格不仅体现了一个人的技术水平,从某种意义上说也体现了一个企业的形象。好的、规范的编码风格,对于整个项目团队来说显得尤为重要。本...
《VC编程规范-程序员们都应该这样写代码》是一篇针对使用Visual C++(VC++)进行软件开发的专业指南。它强调了一些重要的编程习惯,旨在帮助开发者编写出更加清晰、高效且易于维护的代码。本文将基于提供的标题、...
本篇文章将详细探讨代码行数统计工具的功能、重要性以及如何使用。 首先,代码行数统计(Lines of Code, LOC)是评估软件项目大小的一个常见指标。它涵盖了各种编程语言,如JavaScript、JSP和Java,甚至包括注释和...
在编程领域,提高代码编写效率是每位开发者关注的重点。以下是一些关键的知识点和实践策略,旨在帮助提升编程效率: 首先,扎实的语法基础是关键。在初入软件行业时,由于对编程语言不熟悉,可能会频繁遇到语法错误...
#### 家长写给孩子表扬信篇1 亲爱的孩子, 在这个快速变化的时代,你展现出了对新技术的浓厚兴趣和快速学习能力,这让爸爸妈妈非常骄傲。记得那次我们一起学习编程基础时,你对逻辑的理解速度之快,让爸爸也感到...
本篇文章将重点介绍两款这样的工具:Bootstrap和Maqetta。 **Bootstrap** Bootstrap是由Twitter开发的一款开源前端框架,它提供了一套完整的响应式布局、移动设备优先的Web开发解决方案。Bootstrap的核心特点包括...
本篇将详细探讨如何使用代码统计工具来处理Java项目,以及相关的技术要点。 首先,我们需要明确的是代码统计的目标。在Java环境下,有效的代码行数通常指的是不包括空行、注释行、导入语句等的可执行代码行。这些...
"团队建设共识营共识篇"着重讲述了如何通过理解和改变习惯、构建文化和机制,来打造高效能的IT团队。 首先,习惯与行为的改变是团队建设的基础。习惯是人们日常生活中无意识的行为模式,它们可以是助力,也可以成为...
02参考代码篇.zip电子设计大赛资料下载02参考代码篇.zip电子设计大赛资料下载02参考代码篇.zip电子设计大赛资料下载02参考代码篇.zip电子设计大赛资料下载 1.合个人学习技术做项目参考合个人学习技术做项目参考 2....
因此,本篇文章将依据标题和描述来展开“每天写出好代码的5个建议”的相关内容。 ### 每天写出好代码的5个建议 #### 一、保持代码简洁清晰 在软件开发过程中,编写简洁、清晰的代码至关重要。一方面,简洁的代码...