ch1编程之道-代码风格的重塑

第一章编程之道代码风格的重塑,陈闻杰华东师范大学软件学院,Linux高级编程与企业软件开发,Anyfoolcanwritecodethatacomputercanunderstand.Goodprogrammerswritecodethathumanscanunderstand.-MartinFowler,Agenda,1.1为什么要规范代码风格1.2常用的几种代码风格1.3deWiTTERS风格基本规则1.4代码风格的内容1.4.1标识符的命名规则1.4.2代码布局1.4.3注释,1.1为什么要规范代码风格,计算机科学，计算机文化，计算机技术，计算机艺术正确和规范的关系。,1.2常用的几种代码风格,KflatCIPath，flatNetPath是不好的风格，应该保持一致，使用flatCIPathName，flatNetPathName或者假定path一定是pathname，是字符串，也可以。,变量命名惯例(cont.),总数和数组用aaa_count表示总数用aaas（复数）表示数组如intbook_count表示书籍册数，Bookbooks表示书的数组。?集合？,大小写和连字符,大小写的使用是代码风格的重要体现。不同风格中有不同的大小写使用方法。如匈牙利命名法，Linux命名法等。多单词的连接（也有两种风格）用大写字母连接（Windows风格）如：penColor,GetName()用下划线连接（Linux风格）如：pen_color,get_name(),大小写和连字符(cont.),对于单词较多的，用下划线似乎看起来更清楚。下划线的好处是可以区分一些大写的缩略语。另外，在两个紧凑到单词可以连在一起用大写字母区分，如：原：axIterNextHierPortInstOnHierCellInst()-ax_iter_next_HierPortInst_on_HierCellInst()（注）,大小写和连字符(cont.),建议使用：类型名：大写开头，不用下划线分隔单词如：Color变量名：小写开头，用下划线分隔单词【名词性词组】如：color,pen_color常数、枚举值：全大写，用下划线分隔单词如RED，GREEN函数：小写开头，用下划线。【动词性词组】如draw(),draw_circle()宏定义：通常用大写，如果作函数用也可以用小写。布尔型变量：aaa_is_bbb,aaa_has_bbb.和结果为布尔型的函数：check_aaa_bbb(),大小写和连字符(cont.),微软的命名法：用大写的C开头表示类。（Linux上用的较少）匈牙利命名法（前缀古怪）,函数内部的变量命名,1）惯例单字母变量如i，j，k用于循环的迭代p，q用于循环的指针。2）如果仅有一个或两个单词（8个字母内），不加任何前缀，并可以使用缩写。index可以缩写成idx，（如果是不是函数内部变量不建议用缩写）count可以缩写成cnt，适用于出现范围在10行代码之内。,函数内部的变量命名(cont.),3）如果有三个单词以上或字母数较多，用下划线打头，表示是一个内部变量linkChildCellInst_t*_child_CI_list=NULL;如果不是函数内部变量，建议写成child_CellInst_list,或者再加一个前缀表示模块如mw_child_CellInst_list如果是C+的类的内部变量，可以用m打头表示memberm_child_CellInst_list按deWitters风格，也可写成my_child_CellInst_listCellInst是cellinstance的缩写。同时使用大写区分和下划线区分，可以使得专有名词紧凑在一起，提高可理解性。,函数内部的变量命名(cont.),同一个函数内避免一词多用，比如用newPort一会儿代表parentNewPort，一会儿代表childNewPort。宜用两个变量表示。（除了单字母的i，j，k表示整数序数，p，q，r表示指针迭代，每次作用范围限于一个block中）,函数名风格,函数名应该用动词或动词性词组。大小写（有两种风格）一种是大写开头。一种是小写开头。如果类定义用大写开头，则函数名用小写开头，与变量名一样，只是用动词。,函数名风格(cont.),表示“动作”和表示“状态”要区分开来。如new只表示形容词的意思，如果表示动作，用create,generate,establish，build，setup等。一些相对的词get/set,add/remove,insert/delete,create/destroy,start/stop,increment/decrement,new/old,begin/end,first/last,up/down,next/prev,open/close,load/save,show/hide,enable/disable,resume/suspend,函数名风格(cont.),_aaa命名内部函数（辅助函数）对于一个很大的函数（几百行），如果可以，拆成几个小函数。这些函数在别的地方不会被调用到（即为private函数），可以在函数名字前加下划线_，以示区别，方便阅读。或者说，内部函数（private，只在本文件（模块）内被调用，不会被其他模块调用，则使用下划线，代替模块的名字。如privatevoid_ECO_change_C(char*line,String*strParam).而不用privatevoidaxuhe_ECO_change_C(),1.4.2代码布局,缩进Tabindent。Linus推荐用8.本人推荐用4。并建议直接转换成空格符。8是在较早的显示硬件基础上的。行宽原来一般terminal只支持80个字符每行，但现在可以支持的比较多，所以每行100个字亦可，不必为了缩短，而强制换行。但由于新的编辑环境通常有左边浏览栏，甚或右边也有一些快捷栏，所以长度也不可过长，如超过120个字符。,花括号,K所有GNUEMACS和自由软件基金会的代码都使用这种风格，除此之外没有其他地方使用。大括弧距离两边各两格。,风格选用,1.你老板喜欢哪种风格（你们组的风格）2.相邻组或所用开发包的风格3.我推荐的风格：易于统一管理的BSD风格现在显示器都好了，不在乎多占一点地方，但看着整齐。对齐的好处,if(!axuGetHierPoIByHierPoIMstId(cellId,hierCellInstId,hierPoIMId,if(!axuGetHierPoIByHierPoIMstId(cellId,hierCellInstId,hierPoIMId,花括号的另外用途,IDE中的折叠对一个大函数，如果不想把它拆成几个小函数从而增加函数调用负担，可以加花括号将函数分成几部分。每部分可以单独折叠，方便代码阅读。如:foo()/step1/step2变量定义的局部性对于较新的编译器，变量定义局限于所在的block（花括号对）中。在适当的时候加花括号可以避免内部变量范围过大。（注：早期编译器只能在函数开头部分定义变量）,空格，分隔,函数类型和变量用一个Tab，至少两个空格隔开。定义时同类型变量之间用逗号和一个空格隔开。（但也不可相距过远，以易于分辨为原则）指针的星号紧靠变量左边。dbObjId_tCIMId,PoIMId,cellInstId,portInstId;axCellInst_t*cellInst;axPortInst_t*portInst;dbObjTypeId_tPoIMType;dbIteratorId_titerId;stdBoolean_tdone;应改为：dbObjId_tCIMId,PoIMId,cellInstId,portInstId;axCellInst_t*cellInst;axPortInst_t*portInst;dbObjTypeId_tPoIMType;dbIteratorId_titerId;stdBoolean_tdone;,空行,每个函数定义之间至少空两行函数分界处除空行外，可以加注释行分割如/-/=函数内部重要分界处可以空一行,1.4.3注释,注释的原则可以不注释就不注释（让代码自己说明）需要注释一定注释。（关键地方挑明）注释的类型行注释/块注释/*/注释风格比/*注释风格*/好的地方对于多行注释,diff时能都显示出来.或者块注释在每行前加*,注释的场合,文件头版权文件（模块）更新历史文件（模块）重要数据结构和算法概要。简述数据结构和概要，并说明详尽文档编号。文件内出现一些缩略语或名词的解释说明函数说明函数内部说明,版权,在公司中通常是固定的，放在文件最上面。在另外一些版权，如GPL也有些会在项目目录里有个专门的COPYRIGHT文件,/*ACOMPANYCONFIDENTIAL*Thisisanunpublished,proprietaryworkofACOMPANY,Inc.,andis*fullyprotectedundercopyrightandtradesecretlaws.Youmaynotview,*use,disclose,copy,ordistributethisfileoranyinformationcontained*hereinexceptpursuanttoavalidwrittenlicensefromACOMPANY.*/,/*ThisfileispartoftheOpenBabelproject.ThisiscopyrightundertheGNUGeneralPublicLicense(GPL)Formoreinformation,see*/,文件信息,/*FILENAME:sysdep.h*MODULE:Systemdependenciesheader*ABSTRACT:Thisheaderholdstheinformationprogramsneedto*knowconcerningO/S,hardware,andothersystemlevelthangs.*CONVENTIONS:*UselowercaseforallO/S&hardware#definesevenifitis*notcustomarytodoso(ieibminsteadofIBM).*COPYRIGHT(C)1988-1993,ACOMPANYInc.,ALLRIGHTSRESERVED.*COPYRIGHT(C)1987,OPTIMALSOLUTIONSINC.,ALLRIGHTSRESERVED.*,版本修改历史,简单记录重要改动。尤其是已发布版本的修订版。处于新建阶段的文件其版本历史可以不记录在这里,HISTORY:=+=+=+=80=90=100=Flag|Author|Updatedate|Description(projectnameorstarnameanddescription)|=|=|=|=|=|=wjchen0609wjchen2006/09/1809/30PROJ:2007.03-MW-LOG-400:DCsimplificationSomethingmore.wjchen0610wjchen2006/10/0110/30-detaileddescriptionforcodechange(ifnecessary):refertospec.wjchen0609:.f.adddddddddddddddddddddddddddddddddddddddddddddddddddddddsadfassssafsdsddsdsdsdsdssdsdsdsdsdsdsdsdsdsdsdsdsdsdddddddddddddasfddddddddddddddddddddddddddddddddddddddddddasddddddddddddddddddddwjchen0513:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddsadfassssafsdsdsdsdsdsdsdsdsdsdsdsdsdsdsdsdsdsdsdsdsdsdddddddddddddasfddddddddddddddddddddddddddddddddddddddddddasdddddddddddddddddddd,版本修改历史(cont.),在内部代码更动处加flag，便于搜索出改动内容,/wjchen0608:patch单行patch注释/wjchen0608区块patch注释/wjchen0608,缩略语说明,在本模块或本文件中用到的（如在函数名，变量名等地方）一些缩略语，放在一起，做说明。有利于程序阅读。,LAN:LocalAreaNetworkWSN:WirelessSensorNetwork,文件结构和算法说明,详细的文件结构和算法说明一般会有专门文档。但很多文档不在代码库中，因此在代码中直接做一个简单解释，有利于快速阅读代码。,我的个人注释风格,函数，模块头注释/*/重要模块/,我的个人注释风格(cont.),/2.第二步/适当使用用把大函数分割成几块，便于理解和阅读（新型代码阅读器可以展开或收缩花括号）/小段解释/2.2/(2.2)/2)/wjchen0608:patch,我的个人注释风格(cont.),用/XX表示废弃旧代码，而非一般的说明注释。用/XX表示废弃的说明用/(_)表示需要表示需要注意的地方（像一张睁大眼睛（或带着眼镜）的脸）或简写作用/?表示可能有问题的代码。/!表示重要说明用/+表示新增代码,我的个人注释风格(cont.),/YY表示该代码被下面的代码替换（Y像一个箭头）如：/YYaxGetNetName(cellId,flatNetId,我的个人注释风格(cont.),/+wjchen:newcodeshere./+,纯粹视觉效果,1.文件几大功能区分界线/PARTI.MACRODEFINIATIO