Another Java Geek

这是个老生常谈的话题，多数程序员对此应该都并不陌生，不过从我不太长的从业经历来看，具有良好编码风格的程序员实在是凤毛麟角。个人感受：越优秀的程序员，越具有良好的编码风格。或者换个角度说，有良好编码风格的程序员，其它方面也差不到哪儿去。正所谓：见微知著，细节决定成败，一屋不扫何以扫天下。 关于编码风格，有两本很不错的书：一本是林锐博士的《高质量C/C++编程指南》，一本是bob大叔的代码整洁之道》）。前者适合C/C++程序员，后者适合Java程序员。在我初学编程时，看了《高质量C/C++编程指南》的电子版，有意识地实践，基本上奠定了此后的编码风格。《代码整洁之道》是去年有次部门购书时报的书单之一，由于里面的很多原则早已耳熟能详，我花了两三个晚上快速扫了一遍，然后推荐给组内其它成员看。之所以谈起这个话题，并不是想表明自己的编码风格有多好，只是最近有新人入职，我首先与其强调编码风格，因此有必要将一些心得、想法加以整理，贴到博客上。 代码风格是很多编码习惯的统称，例如：命名、注释、空格/空行、缩进、对齐、括号的使用、函数/方法的设计、概念的组织、抽象层级，等等。好的风格在于一致性，拿命名来说，骆驼命名法、下划线命名法、匈牙利命名法等各有其适用范围，如果你采用某种命名法，就当在你的程序中以一贯之地使用，假如混用就是不良风格了。 在一个多人项目团队里，统一的、整洁的代码风格有很多好处： 易于阅读、理解和调试，从而减少维护成本、提高生产率； 每个人可以快速切入和接手其它人的工作，在人员更替时减少交接成本； 提高团队成员之间的舒适感和信任感，大家写出的代码如出一辙，相互更容易悦纳对方，并且增强信任感； 高质量的代码，加上前述的好处，将提升产品的稳定性和团队的执行力。 计算机教育要从娃娃抓起，编码风格要从新人抓起 不少人认为编码风格无关紧要（特别是项目经验、工程经验较少的人），不注意培养编码风格，编码完全意识流，写哪算哪，只要运行结果正确就完事，一旦定型，很难改变，随着你的工作年限和资历的增长，不会有人监督你，不经意间，造成很高的维护成本，影响自身成长，于人于已带来诸多不便。良好的编码风格，需要一开始有意识地训练一段时间，可能是几周几月甚至更长时间，但最终会从中受益，良好的编码风格有助于提高效率，从而将时间精力解放出来，去做更大范围的或更有意义的事情。

近期部门在做新系统的开发，子系统和子系统之间免不了需要约定各种各样的接口；我们负责的子系统内部，在进行系统设计和模块划分时，也需要定义各个模块之间的接口。由于各个子系统固有的异构性，以及参与人员的个人背景和对问题理解等方面的不同，对接口的约定难免有分歧，因此，经常会翻来覆去的讨论和修改接口。 这里有一篇关于API设计的文档，API是应用编程接口，虽然我们平时所约定的接口并不全是公开的API，但是关于API设计的原则和方法，对于普通的接口设计，同样具有很好的借鉴意义。我摘录其中的主要思想，结合在别处所见的关于接口设计的原则，并加以整理，记录于此（原文中出现的“API”，这里大多换成了“接口”，替换之后某些地方的意思可能不大通顺）。 —————————分割线————————— 好接口的几个特征 1.易于学习和记忆 2.产生易读的代码 3.难以被误用 4.易于扩展 5.完整性 注意：“最小化”和“一致性”没有出现在这个列表之中，它们已被其它特征所涵盖了。因为，臃肿的、不一致的接口，很难被学习和记忆，并且难以扩展。 “最小化”是指尽可能让模块对外只公开最少的部分。这里的“模块”可以是一个类、一个包、一个组件或一个子系统等。类应尽可能拥有最少的public方法或成员；包尽可能拥有最少的公开类；组件尽可能拥有最少的配置参数；子系统对外提供尽可能少的公开接口，等等。 “一致性”等同于“概念完整性”，要让一个复杂系统保持架构师愿景中的条理清晰、前后一贯的设计，必须遵循“概念完整性”原则。《人月神话》及《设计原本》的作者Frederick Brooks曾写道：“概念完整性是最重要的系统设计原则。一个省略了某些不协调的功能特性、但保持一组合理设计意图的系统，要远胜于一个包含很多初衷良好、但相互独立且不协调的意图的系统”。 1.易于学习和记忆 易于学习的接口应当具有一致的命名规范和模式，为相同的概念使用相同的名字，为不同的概念使用不同的名字。 最小化的接口容易记忆，因为需要记住的东西也少。一致性的接口容易记忆，因为你可以在一个地方应用先前在其它地方已经学会的规则。 接口并不仅仅是类和方法的名字，而且还包含它们的语义。接口的语义应尽可能的简单、清晰，并且遵循最小惊奇原则（the principle of least surprise），让常见的任务简单易行；不常见的工作可行，但不会让用户过分关注；解决特殊问题时，不要让解决方案不必要的过度通用。 2.产生易读的代码 程序代码一经写就，会被不同的开发者读（并且除错和修改）多次。易读的代码可能需要花点时间来写，但是可以节省产品周期中的其他时间。易读的代码容易文档化和维护，而且不大可能包含bug，因为易读性让bug无处遁形。 易读的代码可能简洁也可能啰嗦，不管哪种情况，它总是处在恰当的抽象层级上——既不隐藏重要的事情，也不强制程序员指定不相关的信息。 3.难以被误用 经过良好设计的接口，更容易编写出正确的代码，而且会促进好的编程实践。它不会强制使用者按照严格的顺序调用方法、注意隐含的副作用或奇异的语义。 4.易于扩展 接口会随时间变化，有可能向已有模块添加新类、向已有类添加新的方法、向已有方法中添加新的参数、增加新的枚举值等，设计接口时应当将此谨记于心。接口越复杂，在新概念和已有概念之间越有可能发生冲突。此外，在接口初始设计阶段就应该考虑二进制兼容性。 5.完整性 理想情况下，接口应当是完整的，允许使用者完成任何他们想做的事情。完整的接口并不是要提供所有的功能，但至少可以允许用户扩展或自定义现有接口。 完整性会随时间而变化，随着时间的推移，可能会有新功能逐步添加到已有接口之中。 接口设计的流程 1.仔细研究需求 咨询他人，看看别人想要什么样的功能。 2.设计之前先写用例 一个很常见的错误——编写组件库时，先实现功能，再设计接口，然后发布。这种方式设计的接口，会反映出底层代码的结构，而不是调用者愿意看到的样子。 3.看看有没有现存的相似接口 这样有可能从现有相似接口的设计中学习有用的东西，避免重蹈覆辙，复用已有的概念，并保持一致性。 4.先设计，后实现 首先定义接口和它的语义，不要担心实现的复杂度。一个接口直观但实现复杂且布满trick的库，要优于一个实现简洁但接口复杂的库。 5.找人帮你评测接口 寻求反馈，特别是负面的。这些意见更能帮助你改进设计。 6.使用你的接口编写示例 这有助于你发现潜在的问题，而且可以帮助别人了解如何使用你的接口。 7.做好扩展的准备 这要求你了解现实的场景，并思考可能的情况。 8.内部API没评测之前不要发布 有些API一开始是内部使用的，后来大家觉得很有用，才公开发布。一个常见的错误就是发布之前没有进行完整的测试。 9.宁缺毋滥 如果对接口的功能不是很确定，先不要发布。 接口设计原则 1.命名 名字要能解释自己，要遵从英语语法。千万别一会英文单词，一会汉语拼音。 参数的命名也要清楚明白。尽量少用bool类型的参数，这样的代码不好读。 命名要统一。不要混用类似widget和control这类词语，这会让用户乱猜。参数的顺序也要一致。 [...]