第一章第一章编程之道编程之道代码风格的重塑代码风格的重塑陈闻杰华东师范大学软件学院Linux高级编程与企业软件开发Any fool can write code that a computer can understand. Good programmers write code that humans can understand. - Martin FowlerAgendaAgenda1.1 为什么要规范代码风格1.2 常用的几种代码风格1.3 deWiTTERS 风格基本规则1.4 代码风格的内容1.4.1 标识符的命名规则1.4.2 代码布局1.4.3 注释1. 编程之道-代码风格的重塑1.1 1.1 为什么要规范代码风格为什么要规范代码风格计算机科学，计算机文化，计算机技术，计算机艺术正确正确和规范规范的关系。1. 编程之道-代码风格的重塑1.2 1.2 常用的几种代码风格常用的几种代码风格K&RK&R风格风格 BSDBSD风格风格 GNUGNU风格风格 WindowsWindows风格风格deWiTTERS deWiTTERS 风格风格1. 编程之道-代码风格的重塑1.3 deWiTTERS 风格deWiTTERS 风格的基本规则有3条：1）尽量可理解2）尽量可读，除非与以上规则矛盾3）尽量简单，除非与以上规则矛盾反过来说，我们写一段程序要尽量简单，除非影响到了它的可读性和可理解性。代码风格和具体使用的编程语言有关，但基本规则是不变的。1. 编程之道-代码风格的重塑1.4 1.4 代码风格的内容代码风格的内容哪些属于语言定义？哪些属于代码风格？正确 vs 规范标识符的命名规则变量名、常量名、宏名、函数名、类型名、类名、对象名、方法名文件名、模块名、项目名提交安装文件或文档的命名布局（布白）缩进空格，空行花括号的位置和对齐1. 编程之道-代码风格的重塑注释版权注释文件版本历史文件或模块的功能函数注释函数内注释文件结构和项目结构一个项目划分成几个文件文件的组织1. 编程之道-代码风格的重塑1.4.11.4.1标识符的命名规则标识符的命名规则 标识符包括标签（label），函数名（function name），宏名，常量名，变量名，宏名，以及文件名，模块名。1. 用英语，要求准确，简单，专业。避免拼音，避免容易误解的多义词2. 根据情况是否用缩写。用单词的前面部分缩写，可以不必管词性（名词，形容词，动词），单复数，时态等。但有时也可能因此带来不便。1. 编程之道-代码风格的重塑缩写缩写函数名，变量名不是非常必要缩写的不用缩写。缩写分为：1。字头缩写(Acronyms), 宜用大写。如 HECO._HECO_.必要情况下可以用小写。如果作为一个很著名的，有明确含义的缩写，如HECO，则用缩写比不用缩写更清楚。2。长单词缩短：有几个原则： a）通用，如 temp表示 临时，则表示温度时应用全称temperature或 temper b）同一个模块（项目，文件，函数。）应保持一致。 c）7个字母以下的单词通常不缩写。 d）用单词的前一部分 e）用辅音字母。 d和e通常只选择一个。并且以d为好，因为用grep搜索单词的前面部分可以搜索出所有经过和没有经过缩写的单词。1. 编程之道-代码风格的重塑缩写缩写 (cont.) (cont.)缩写宜遵从约定或惯例。固定含义的缩写temp tmp 表示temporary temporarily可以用temper表示 temperaturecom 通常表示 communicate/communicationcomp （或cmp）表示compare/comparation函数内部的局部变量（作用范围很小，或者函数很小）可以用缩写，如 index缩写为 idx，count缩写为cnt等。但对于较长的函数，用全称可能更清楚。1. 编程之道-代码风格的重塑缩写缩写 (cont.) (cont.)以下为不好的例子： axGetCellInstMasterByName() axuGetPortInstMstByName()同一个文件中Master既有缩写，又有不缩写的。 1. 编程之道-代码风格的重塑全局变量，局部变量，参数全局变量，局部变量，参数 全局变量，局部变量，参数。全局变量，局部变量，参数。标识符包括标签（label），函数名（function name），宏名，常量名，变量名，宏名，以及文件名，模块名。变量名有 全局变量，局部变量（函数内部），参数名。最好在命名时有所区别。全局变量：尽量避免使用。如果需要，将一个模块内所有全局变量集中在一起。参数：需要与局部变量能区分开来，尤其是函数较大的时候。_IN_OUT_INOUT局部变量:1. 编程之道-代码风格的重塑变量命名惯例变量命名惯例尽量避免使用 number这个有歧义的词。序号 index总数（计数） count唯一标识 ID大小 size长度 length 或 len但有些固定的用法，比如行号lineNumber好像还是 沿用旧例LineNum或 LineNo.1. 编程之道-代码风格的重塑变量命名惯例变量命名惯例 (cont.) (cont.)._name ._name 表示字符串类型，不必说明表示字符串类型，不必说明String flatPortName, flatCIPath, flatCIName, flatNetPath, flatNetName;flatCIPath， flatNetPath 是不好的风格，应该保持一致，使用flatCIPathName， flatNetPathName或者假定path一定是pathname， 是字符串，也可以。1. 编程之道-代码风格的重塑变量命名惯例变量命名惯例 (cont.) (cont.)总数和数组用 aaa_count 表示总数用aaas （复数）表示数组如int book_count 表示 书籍册数，Book books表示书的数组。? 集合？1. 编程之道-代码风格的重塑大小写和连字符大小写和连字符大小写的使用是代码风格的重要体现。不同风格中有不同的大小写使用方法。如匈牙利命名法，Linux命名法等。多单词的连接 （也有两种风格）用大写字母连接（Windows风格） 如：penColor, GetName()用下划线连接（Linux 风格） 如：pen_color, get_name()1. 编程之道-代码风格的重塑大小写和连字符大小写和连字符(cont.)(cont.)对于单词较多的，用下划线似乎看起来更清楚。下划线的好处是可以区分一些大写的缩略语。另外，在两个紧凑到单词可以连在一起用大写字母区分，如：原：axIterNextHierPortInstOnHierCellInst()-ax_iter_next_HierPortInst_on_HierCellInst() （注）1. 编程之道-代码风格的重塑大小写和连字符大小写和连字符(cont.)(cont.)建议使用建议使用：类型名类型名：大写开头，不用下划线分隔单词如：Color变量名变量名：小写开头，用下划线分隔单词【名词性词组】如：color, pen_color常数、枚举值常数、枚举值：全大写，用下划线分隔单词如 RED， GREEN函数函数：小写开头，用下划线。 【动词性词组】如 draw(), draw_circle()宏定义：宏定义：通常用大写，如果作函数用也可以用小写。布尔型变量布尔型变量：aaa_is_bbb, aaa_has_bbb.和结果为布尔型的函数结果为布尔型的函数：check_aaa_bbb() 1. 编程之道-代码风格的重塑大小写和连字符大小写和连字符(cont.)(cont.)微软的命名法：用大写的C开头表示类。（Linux上用的较少）匈牙利命名法（前缀古怪）1. 编程之道-代码风格的重塑函数内部的变量命名函数内部的变量命名1）惯例单字母变量 如i，j，k 用于循环的迭代 p，q 用于循环的指针。2）如果仅有一个或两个单词（8个字母内），不加任何前缀，并可以使用缩写。 index 可以缩写成idx，（如果是不是函数内部变量不建议用缩写） count可以缩写成cnt， 适用于出现范围在10行代码之内。 1. 编程之道-代码风格的重塑函数内部的变量命名函数内部的变量命名(cont.)(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_list CellInst 是 cell instance 的缩写。同时使用大写区分和下划线区分，可以使得专有名词紧凑在一起，提高可理解性。 1. 编程之道-代码风格的重塑函数内部的变量命名函数内部的变量命名(cont.)(cont.)同一个函数内避免一词多用，比如 用 newPort 一会儿代表 parentNewPort，一会儿代表childNewPort。宜用两个变量表示。（除了单字母的i，j，k表示整数序数，p，q，r表示指针迭代，每次作用范围限于一个block中）1. 编程之道-代码风格的重塑函数名风格函数名风格 函数名应该用动词或动词性词组。大小写 （有两种风格）一种是大写开头。一种是小写开头。如果类定义用大写开头，则函数名用小写开头，与变量名一样，只是用动词。1. 编程之道-代码风格的重塑函数名风格函数名风格 (cont.) (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 1. 编程之道-代码风格的重塑函数名风格函数名风格 (cont.) (cont.)_aaa _aaa 命名内部函数（辅助函数）命名内部函数（辅助函数）对于一个很大的函数（几百行），如果可以，拆成几个小函数。这些函数在别的地方不会被调用到（即为private函数），可以在函数名字前加下划线_，以示区别，方便阅读。或者说，内部函数（private，只在本文件（模块）内被调用，不会被其他模块调用，则使用下划线，代替模块的名字。如private void _ECO_change_C(char * line, String *strParam).而不用 private void axuhe_ECO_change_C() 1. 编程之道-代码风格的重塑1.4.2 1.4.2 代码布局代码布局缩进Tab indent。 Linus 推荐用8.本人推荐用4。 并建议直接转换成空格符。8是在较早的显示硬件基础上的。行宽行宽原来一般terminal只支持80个字符每行，但现在可以支持的比较多，所以每行100个字亦可，不必为了缩短，而强制换行。但由于新的编辑环境通常有左边浏览栏，甚或右边也有一些快捷栏，所以长度也不可过长，如超过120个字符。1. 编程之道-代码风格的重塑花括号花括号K&RK&R风格：风格：if () 以传说中的Kernighan & Ritchie之名命名，因他们的样例代码而被广为接受。又因Unitx内核使用这种风格，所以又被称作Kernel Style，也被它的信徒称作One True Brace Style。也因为C代码主要使用这种风格，也被其他类C语言的使用者称作C风格。这种风格的流行，一是因为大部分教学书籍使用这种风格以节约纸张成本，二是随着Java的普及而被广泛接受。优点优点是代码相当紧凑，对低分辨率的显示器和打印文稿来说很有价值；缺点是缺点是在有些情况下匹配大括弧有些困难，并且也因此产生很多子派别。如：if () else 与if () else 1. 编程之道-代码风格的重塑BSDBSD风格：风格：if ()以Berkeley黑客Eric Allman之名命名，也叫Ansi风格，大括弧独占一行。这是除了K&R风格外，唯一的在Java社群里大量使用的风格，而Dos/Windows程序员大部分使用这种风格，在这个社群里也被称作标准风格。优点优点是在所有的地方大括弧都是对称的，大部分人认同这种风格的代码更易读；缺点缺点是浪费空间，比如：try DoSomething();catch DoSomething();如果你无法忍受浪费的行，最好的办法就是用这些行来写注释。1. 编程之道-代码风格的重塑GNUGNU风格：风格：if () DoSomething(); 所有GNU EMACS和自由软件基金会的代码都使用这种风格，除此之外没有其他地方使用。大括弧距离两边各两格。1. 编程之道-代码风格的重塑风格选用风格选用1. 1. 你老板喜欢哪种风格你老板喜欢哪种风格 （你们组的风格）（你们组的风格）2. 2. 相邻组或所用开发包的风格相邻组或所用开发包的风格3. 3. 我推荐的风格：我推荐的风格：易于统一管理的BSDBSD风格风格现在显示器都好了，不在乎多占一点地方，但看着整齐。 对齐的好处对齐的好处if(!axuGetHierPoIByHierPoIMstId(cellId,hierCellInstId,hierPoIMId,&hierPortInstId,&hierPortInst)|!hierPortInstId)gotoerrorReturn;if(!axuGetHierPoIByHierPoIMstId(cellId,hierCellInstId,hierPoIMId,&hierPortInstId,&hierPortInst)|!hierPortInstId)gotoerrorReturn;1. 编程之道-代码风格的重塑花括号的另外用途花括号的另外用途IDE中的折叠对一个大函数，如果不想把它拆成几个小函数从而增加函数调用负担，可以加花括号将函数分成几部分。每部分可以单独折叠，方便代码阅读。如 : foo() / step 1 / step 2 变量定义的局部性对于较新的编译器，变量定义局限于所在的block （花括号对）中。在适当的时候加花括号可以避免内部变量范围过大。 （注：早期编译器只能在函数开头部分定义变量）1. 编程之道-代码风格的重塑空格，分隔空格，分隔函数类型和变量用一个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. 编程之道-代码风格的重塑空行空行每个函数定义之间至少空两行函数分界处除空行外，可以加注释行分割如 /- / /=函数内部重要分界处可以空一行1. 编程之道-代码风格的重塑1.4.3 1.4.3 注释注释注释的原则可以不注释就不注释（让代码自己说明）需要注释一定注释。（关键地方挑明）注释的类型行注释 / 块注释 /* */ / 注释风格注释风格 比比 /* /*注释风格注释风格*/ */ 好的地方好的地方对于多行注释, diff 时能都显示出来. 或者块注释在每行前加 * 1. 编程之道-代码风格的重塑注释的场合注释的场合文件头版权文件（模块）更新历史文件（模块）重要数据结构和算法概要。简述数据结构和概要，并说明详尽文档编号。文件内出现一些缩略语或名词的解释说明函数说明函数内部说明1. 编程之道-代码风格的重塑版权版权在公司中通常是固定的，放在文件最上面。在另外一些版权，如GPL也有些会在项目目录里有个专门的COPYRIGHT文件/*ACOMPANYCONFIDENTIAL*Thisisanunpublished,proprietaryworkofACOMPANY,Inc.,andis*fullyprotectedundercopyrightandtradesecretlaws.Youmaynotview,*use,disclose,copy,ordistributethisfileoranyinformationcontained*hereinexceptpursuanttoavalidwrittenlicensefromACOMPANY.*/*ThisfileispartoftheOpenBabelproject.ThisiscopyrightundertheGNUGeneralPublicLicense(GPL)Formoreinformation,see*/1. 编程之道-代码风格的重塑文件信息文件信息/*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.*1. 编程之道-代码风格的重塑版本修改历史版本修改历史简单记录重要改动。尤其是已发布版本的修订版。处于新建阶段的文件其版本历史可以不记录在这里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:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddsadfassssafsdsdsdsdsdsdsdsdsdsdsdsdsdsdsdsdsdsdsdsdsdsdddddddddddddasfddddddddddddddddddddddddddddddddddddddddddasdddddddddddddddddddd1. 编程之道-代码风格的重塑版本修改历史版本修改历史 (cont.) (cont.)在内部代码更动处加 flag，便于搜索出改动内容/wjchen0608:patch单行patch注释/wjchen0608区块patch注释/wjchen06081. 编程之道-代码风格的重塑缩略语说明缩略语说明在本模块或本文件中用到的（如在函数名，变量名等地方）一些缩略语，放在一起，做说明。有利于程序阅读。LAN:LocalAreaNetworkWSN:WirelessSensorNetwork1. 编程之道-代码风格的重塑文件结构和算法说明文件结构和算法说明详细的文件结构和算法说明一般会有专门文档。但很多文档不在代码库中，因此在代码中直接做一个简单解释，有利于快速阅读代码。1. 编程之道-代码风格的重塑我的个人注释风格我的个人注释风格函数，模块头注释/*/ 重要模块/1. 编程之道-代码风格的重塑我的个人注释风格我的个人注释风格 (cont.) (cont.)/ 2. 第二步/适当使用用 把大函数分割成几块，便于理解和阅读（新型代码阅读器可以展开或收缩花括号）/ 小段解释/ 2.2 /(2.2) / 2)/ wjchen0608: patch 1. 编程之道-代码风格的重塑我的个人注释风格我的个人注释风格 (cont.) (cont.)用 /XX 表示废弃旧代码，而非一般的说明注释。用 /XX 表示废弃的说明用/(_) 表示需要表示需要注意的地方 （像一张睁大眼睛（或带着眼镜）的脸） 或简写作用/? 表示可能有问题的代码。/!表示重要说明用/+ 表示 新增代码1. 编程之道-代码风格的重塑我的个人注释风格我的个人注释风格 (cont.) (cont.)/YY 表示该代码被下面的代码替换（Y 像一个箭头 ）如： /YY axGetNetName(cellId, flatNetId, &flatNetName); /YY strcpy(flatNetFullName, flatNetName); axGetNetName(cellId, flatNetId, &flatNetFullName);1. 编程之道-代码风格的重塑我的个人注释风格我的个人注释风格 (cont.) (cont.)/+ wjchen: new codes here./+ 1. 编程之道-代码风格的重塑纯粹视觉效果纯粹视觉效果1. 文件几大功能区分界线/ PART I. MACRO DEFINIATION/2. 函数定义分界线。/ -/ Function foo./-3. 重要函数调用. ret= key_function()/1. 编程之道-代码风格的重塑【总结】注释类别【总结】注释类别注释包括1 1。文件头注释，函数头注释。文件头注释，函数头注释。 版权，创建及修改历史，缩写说明，（函数）参数及返回值说明（如果参数名及函数名可以一望而知，则不必说明以保持简洁）2 2。关键算法注释。关键算法注释（成块） 用一段话表示大体的结构，可以放在文件头或合适的位置。3 3。函数内代码结构注释。函数内代码结构注释。（一段代码） 用三行顿点式构成主要架构4 4。单句语句注释。单句语句注释 通常的注释，用单行，附尾或 /*/ 5 5。 修订版本标志修订版本标志 /wjchen0607315 5。废弃代码，替换代码及相关说明。废弃代码，替换代码及相关说明。 /XX /YY /XX/YY6 6。供外部工具使用的特殊标记。供外部工具使用的特殊标记 如给oxygen提取文档用但标记7 7。其他标记。其他标记 /! 特别注意 /? 有问题的代码 /(_):值得注意，可能有问题 （个性化代码，像个睁大眼睛的或带着眼镜的人脸）1. 编程之道-代码风格的重塑废弃代码和被替换代码均为临时保留。如无重要理由，正式代码库中应予以删除。1. 编程之道-代码风格的重塑参考资料参考资料Tao of Coding by Koen Witters （必看）http:/www.chris-lott.org/resources/cstyle/witters_tao_coding.html 林锐，韩永泉 高质量程序设计指南高质量程序设计指南C+/CC+/C语语言（第三版）言（第三版）萨特，亚历山德雷斯库 著，刘基诚 译, C+C+编程编程规范规范:101:101条规则、准则与最佳实践条规则、准则与最佳实践（图灵程序设计丛书） （美）米斯菲尔特，（美）布姆加德纳，（美）格雷 著，罗小平 译, C+ C+ 编程风格编程风格( (英汉对照英汉对照) ) 1. 编程之道-代码风格的重塑1. 编程之道-代码风格的重塑作业作业上交一份自己以前做过的项目的源代码。