代码质量随想录四排版不只是为了漂亮Word格式.docx
《代码质量随想录四排版不只是为了漂亮Word格式.docx》由会员分享，可在线阅读，更多相关《代码质量随想录四排版不只是为了漂亮Word格式.docx（11页珍藏版）》请在冰豆网上搜索。
100/*以Kbps计量的吞吐量*/,
400/*以毫秒计的网络延迟*/,
250/*包抖动*/,
5/*丢包百分比*/;
}
上面这个例子是ARC书中所举的，我认为很恰当。
该类的三个静态字段功能类似，都指代某种环境下的网络模拟器，所以排版也应该相似。
每行都只写一个实参，而且后面用行内注释的形式解释该实参的意思。
在垂直方向上的对齐做得也很好：
字段申明前面空2格，实例化语句前面空4格，各实参前面空6格（以上数字非实指，仅是举例而已）。
这样要修改某个参数，很快就能定位到它，而且以后如果增加类似的字段，如badWIFI，也可以比照这个格式来，便于维护。
由以上范例还可引出一个问题，那就是在实例化或方法调用中，经常会遇到一些孤立的魔法数字（magicnumber），如果确有必要为它起名，那么不妨执行一个小的重构，以常量来代替它。
反之，如果是大段的硬数值，则不一定非要为每个值都起一个名字，例如：
TcpConnectionSimulatorwifi=
WIFI_KBPS_THROUGHPUT,
WIFI_LATENCY,
WIFI_JITTER,
WIFI_PACKET_LOSS_PERCENT;
这样反而显得累赘。
不妨像上例那样采用行内注释的办法来解释这些硬值的意思。
承上，ARC的作者又推导出一条建议，就是将相似的方法调用参数注释提取到一处，例如：
//TcpConnectionSimulator（throughput,latency,jitter,packet_loss
//[Kbps][ms][ms][percent]
newTcpConnectionSimulator（500,80,200,1;
newTcpConnectionSimulator（45000,10,0,0;
newTcpConnectionSimulator（100,400,250,5;
说实在的，以前在工作中还没太重视这个问题，一来是觉得我在写Javadoc时一贯非常完备，出现这种情况时只需靠鼠标悬停就可知道某个方法或构造器的具体信息了；
二来嘛，也是想着如果使用大量数值的调用代码多到无法管控，我可能会祭出配置文件这个大旗来，将它们全部纳入配置中了事。
所以关于以上例子中谈到的这些问题，我觉得还是根据大家的具体实践来理解为好，不要机械地寻求一致。
2.将大量相似的嵌套式、接续式调用逻辑整合到共用方法之中，即利于排版，又可凸显重要数据
在测试用例等代码中，经常会出现类似下面这种状况：
//某受测类中：
//将类似"
DougAdams"
这样的不完整称呼进行补全，扩展为"
Mr.DouglasAdams"
的形式。
//如若不能（查不到数据或无法补完），则于error参数中填充错误信息并返回空串。
//此方法会置空错误信息接收参数。
publicStringexpandToFullName（DatabaseConnectionconn,
StringpartialName,
ErrorMessageReceivererror{...}
//某测试方法中：
DatabaseConnectionconnection=...;
ErrorMessageReceivererror=...;
assertEquals（expandToFullName（connection,"
error,
"
;
assertEquals（error.getMessage（,"
JakeBrown"
Mr.JacobBrownIII"
NoSuchGuy“,error,
nomatchfound"
John“,error,
morethanoneresult"
这符合上面所说的“量大”、“形似”、“嵌套”等特征，而且诸如输入字串、预期结果、预期错误消息等重要的数据，被埋没于connection、error、getMessage（等技术细节之中。
所以可以借由美化版式之机进行重构：
checkPartialToFull（"
"
Mr.JakeBrownIII"
"
NoSuchGuy"
John"
privatevoidcheckPartialToFull（StringpartialName,
StringexpectedFullName,
StringexpectedErrorMessage{
//connection已被提取为测试固件类的成员变量
StringactualFullName=expandToFullName（connection,partialName,error;
assertEquals（expectedErrorMessage,error.getMessage（;
assertEquals（expectedFullName,actualFullName;
如此一来一举三得：
既消除了重复代码，同时美化了版式，凸显了输入字串、预期结果、预期错误消息等重要数据，顺带着还方便了后续测试数据的维护。
这种藉由版式整理带来的重构，我看可以有！
3.明智地使用纵向对齐来减少拼写错误、厘清大量同组数据。
我觉得这一条和第1条有重复，其实也属于类似功能的代码应具类似版式之意，不过既然ARC作者将它单列，我想可能是为了强调纵向对齐的好处吧。
//将POST参数中的属性分别提取至各个局部变量中
ServletRequestrequest=...;
Stringdetails=request.getParameter（"
details"
Stringlocation=request.getParameter（"
location"
Stringhone=request.getParameter（"
phon"
Stringemail=request.getParameter（"
email"
Stringurl=request.getParameter（"
url"
经由纵向对齐，很容易看出第三个局部变量这行的错误：
将变量名“phone”误写为“hone”，参数名的“phone”则错成了”phon“。
另外，在进行结构体数据、数组成员等这种同组数据排列时，也可以充分利用版式来厘清每个元素的意义。
ARC的作者就大赞wget这个命令行工具在指定参数结构体时，代码排列地很工整。
//非原文，小翔以Java形式改写
Object[][]commands={
//参数名,默认值,类型
{"
timeout"
null,TIMEOUT},
timestamping"
defOpt.timestamp,BOOLEAN},
tries"
defOpt.tryCount,NUMBER},
useproxy"
defOpt.useProxy,BOOLEAN},
useragent"
null,USER_AGENT}
};
这一条建议如果与第1条合并起来说，那就是：
任务相似的代码块应该具有相似的轮廓（ARC的作者叫它silhouette），如行数、缩进、纵向对齐等。
4.使用适当空行与注释，将代码按功能分段
有时候经常在考虑代码与散文或诗的联系，如果从隐喻（metaphor）的观点来看，的确有相似性：
都是信息的载体，都可以用一定的段落来整合文意。
要说区别嘛，前者服务于软件需求，后者服务于社会关系。
前者为了向更低阶的执行机制去接合，所以更加注重语法格式。
我可不是第一个进行这种思维比拟的人，记得台湾的技术畅销书作者侯捷先生（侯俊杰）就曾写过一本《左手程序右手诗》的书。
classFrontendServer{
public:
FrontendServer（;
voidViewProfile（HttpRequest*request;
voidOpenDatabase（stringlocation,stringuser;
voidSaveProfile（HttpRequest*request;
stringExtractQueryParam（HttpRequest*request,stringparam;
voidReplyOK（HttpRequest*request,stringhtml;
voidFindFriends（HttpRequest*request;
voidReplyNotFound（HttpRequest*request,stringerror;
voidCloseDatabase（stringlocation;
~FrontendServer（;
上面的代码挺蜗居的，如果加上适当的空行与说明，就显得清晰多了。
//与用户配置相关的处理函数
//回覆及应答工具函数
//数据库操作工具函数
上述类将声明区按照构建子/析构子、社交功能函数、工具函数这个标准划分为的三大思维区段，工具函数区又按题材划分为消息操作与数据库操作两小段。
这样一来，以后再要维护这份声明代码就会很清爽了。
同理，如果声明一个集合类的接口，也应该按照“增、删、改、查”等概念来将API划分为若干小组，以便帮助代码阅读者理顺思路。
就算是在流水式的业务代码中，也可以用段落来衬托出逻辑的“起、承、转、合”。
//导入用户电子邮件账户中联系人，同本产品中已有的联系人相比对。
//然后展示正在使用本产品但未与用户建立朋友关系的联络人列表。
publicListDataModelsuggestNewFriends（Useruser,PasswordemailPassword{
SocialCirclefriends=user.friends（;
EmailsfriendEmails=friend.dumpAllEmails（;
Contactscontacts=importContacts（user.email,emailPassword;
EmailscontactEmails=contacts.extractAllEmails（;
EmailsproductUserEmails=UserDataCenter.selectEmails（contactEmails;
EmailssuggestedFriends=productUserEmails.subtract（friendEmails;
ListDataModeldisplayModel=newListDataModel（user,friends,suggestedFriends;
returndisplayModel;
上面的代码给人的压迫感很强列，没有思维喘息的机会。
不如把注释拆解，按其逻辑将代码分成小段，为每一段冠以简短标题。
//取得当前用户全部朋友的邮件地址
//引入当前用户电子邮件账户中的联系人
//找出正在使用本产品但尚未与本用户建立朋友关系的联系人
//返回待显示列表的数据模型
欣赏一下上面这段代码吧，每小段以一句概括性的注释引领，然后是两句实现代码，排列得非常整齐，代码的阅读者根据此的版式，很容易就能抓住代码的思维走向：
“2（获取朋友列表）-2（获取联系人邮箱）-2（找出潜在友人）-2（返回数据模型）”。
怎么样，是不是有点儿“起、承、转、合”的意思了？
（大误）
由上例可见，适当地进行代码分段并通过注释来充当代码段的概括语，有助于梳理代码阅读者的思路，也有助于代码修改、维护和后续查错。
比如想做一个“向未使用本社交网站的电邮联络人发送邀请”的功能，扫一眼上述这段清晰排版的代码，大家立刻就能看出，只需要写好测试用例，复制一份suggestNewFriends的代码，把selectEmails改成excludeEmails，就能找到这些潜在的被邀请人了。
给新的方法起个名字，叫inviteContacts，删去多余的程序，然后通过重构提取一下共用代码，再确保测试无误，就可以收工了。
思路顺了，编码的过程自然也就更加流畅了。
好了，小小总结一下吧。
其实代码排版这种略带个人化的东西，不仅仅是让代码看起来更漂亮，其根本目的还是着眼于代码的可读性，要有助于代码的理解、维护、纠错。
具体到执行层面，除了可以参考上述4条建议外，还要注意两方面的问题。
第一个问题，ARC的作者也提到了，那就是很多朋友对代码排版有排斥心理，不愿意认真排版。
有一部分原因是怕浪费时间，还有就是担心代码管理系统会将排版后的代码与排版之前的代码判定为两份截然不同的程序，在版本比对时导致满屏的diff，非常难看。
其实，在现有的成熟IDE之中（抑或各位Geek们惯用的文本编辑器之中）已经有非常完备的功能来支援代码版式的调整了。
比如Eclipse、Netbeans等开发环境，都可以把版式定义文件导出为xml等数据格式，到了陌生的环境时，只需导入即可。
而且代码排版一旦确定，就可以一次性地更改所有项目源码的版式然后提交，这样就可以避免在版本比对时显示过多的修改提示了。
第二个问题就是应该在必要的范围内保持代码排版的一致性。
虽然我刚也说了，代码排版没有绝对的真理，不过，它却应该有一个相对的底线。
在公司与公司之间、团队与团队之间，的确没有必要强行要求一致的版式。
例如我们不宜妄自菲薄，说I记或G社的代码排得如何如何漂亮，同时也不能过分地自高自大，说自己团队的版式是天下最美观、最养眼的。
但是，如果具体到某个项目，尤其是中小型项目里面，那么就要想方设法达成一致的版式规范了，否则将会给代码的阅读、理解与维护造成不必要的障碍。
为此，项目组的成员应该富有的妥协精神，在坚持个人风格这个问题上稍作让步，以求达成大家对代码版式的共识。
比如，小翔在个人项目或由我带队的项目中，通常使用以下版式：
publicclassMyArrayListextendsMyAbstractListimplementsMyCollection{
//静态部分在前：
//静态内部类型区。
同区成员按存取级别排序，高者在前。
/**
*列表容量参数。
*/
publicstaticclassCapacityOptions{
/**初始容量。
*/
privatefinalintinitialElementCount;
/**扩容时新增的容量与扩容前容量之比。
privatefinalintexpandRatio;
...
//静态初始化块与静态字段区。
privatestaticfinalMapcommonCapacityOptions=...;
static{
commonCapacityOptions.put（"
normal"
newCapacityOptions（12,1;
...;
//静态方法区。
*从既有数组中构建列表。
*@paramelements用以构建的数组，不能为null。
*@return构建好的列表
publicstaticListcreate（Object[]elements{
//动态部分在后：
//动态内部类型区。
publicclassMyIterator{
publicObjectnext（{
//动态初始化块与实例成员变量区。
{
privateintcount;
//构造器区。
publicMyList（{
//实例方法区。
//先写本类方法。
voidexpand（{
//其次，从直接超类开始，层层追溯至Object，将各层级上的覆写方法列出。
@Override
publicbooleanadd（Objecte{
//然后按由进至远的顺序，实现接口中的方法。
//同等层级的接口，按其出现在implements、extends子句中的先后顺序，依次实现其方法。
publicvoidclear（{
//最后覆写Object类中的方法。
publicStringtoString（{
//准析构方法区。
protectedvoidfinalize（throwsThrowable{
上述这个“3+5式分段法”（静态部分：
静态内部类型、静态初始化块与字段、静态方法；
动态部分：
动态内部类性、动态初始化块与实例成员变量、构造器、实例方法、准析构方法），小翔在六年多的工作中一直用着，我觉得它对于代码阅读来说，还算满流畅的，在此也分享给大家。
不过，如果现有项目大多数成员要求将左花括号放于新行之首，并要求动态部分出现在静态部分的前边，那么我就会在这个项目中按照大家喜欢的格式来办（并不是随意放弃自己认为合理的版式，而是在某个项目的具体语境下为了求得共识而妥协），同理，类似新行符是\n、\r还是\n\r，空白符是空格还是制表符之类问题，我觉得只要大家认为合适，就没有必要过分争执，定出一个项目内部易于统一管理的规范就好。
再多说一句吧，有同学可能会问，既然Eclipse等IDE中已经可以通过类结构导览视图来显示类代码中的各种成员，那么为何还要如此在乎代码版式呢？
因为不管具体代码怎么排列，视图中都可以调整显示顺序呀。
对于这个问题，我想有时我们不仅仅要通过导览视图来看宏观结构，还需要进行
升级会员 