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

第一章编程之道代码风格的重塑,陈闻杰 华东师范大学软件学院,Linux高级编程与企业软件开发,Any fool can write code that a computer can understand. Good programmers write code that humans can understand. - Martin Fowler,Agenda,1.1 为什么要规范代码风格 1.2 常用的几种代码风格 1.3 deWiTTERS 风格基本规则 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 （复数）表示数组如int book_count 表示 书籍册数，Book books表示书的数组。 ? 集合？,大小写和连字符,大小写的使用是代码风格的重要体现。不同风格中有不同的大小写使用方法。如匈牙利命名法，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_list CellInst 是 cell instance 的缩写。同时使用大写区分和下划线区分，可以使得专有名词紧凑在一起，提高可理解性。,函数内部的变量命名(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，只在本文件（模块）内被调用，不会被其他模块调用，则使用下划线，代替模块的名字。如private void _ECO_change_C(char * line, String *strParam).而不用 private void axuhe_ECO_change_C(),1.4.2 代码布局,缩进 Tab indent。 Linus 推荐用8. 本人推荐用4。 并建议直接转换成空格符。 8是在较早的显示硬件基础上的。 行宽原来一般terminal只支持80个字符每行，但现在可以支持的比较多，所以每行100个字亦可，不必为了缩短，而强制换行。但由于新的编辑环境通常有左边浏览栏，甚或右边也有一些快捷栏，所以长度也不可过长，如超过120个字符。,花括号,K 所有GNU EMACS和自由软件基金会的代码都使用这种风格，除此之外没有其他地方使用。大括弧距离两边各两格。,风格选用,1. 你老板喜欢哪种风格 （你们组的风格） 2. 相邻组或所用开发包的风格 3. 我推荐的风格：易于统一管理的BSD风格 现在显示器都好了，不在乎多占一点地方，但看着整齐。 对齐的好处,if(!axuGetHierPoIByHierPoIMstId(cellId, hierCellInstId, hierPoIMId, ,if(!axuGetHierPoIByHierPoIMstId(cellId, hierCellInstId, hierPoIMId, ,花括号的另外用途,IDE中的折叠 对一个大函数，如果不想把它拆成几个小函数从而增加函数调用负担，可以加花括号将函数分成几部分。每部分可以单独折叠，方便代码阅读。 如 : foo() / step 1 / step 2 变量定义的局部性 对于较新的编译器，变量定义局限于所在的block （花括号对）中。在适当的时候加花括号可以避免内部变量范围过大。 （注：早期编译器只能在函数开头部分定义变量）,空格，分隔,函数类型和变量用一个Tab，至少两个空格隔开。定义时同类型变量之间用逗号和一个空格隔开。（但也不可相距过远，以易于分辨为原则）指针的星号紧靠变量左边。 dbObjId_t CIMId, PoIMId, cellInstId, portInstId; axCellInst_t *cellInst;axPortInst_t *portInst; dbObjTypeId_t PoIMType; dbIteratorId_t iterId; stdBoolean_t done;应改为： dbObjId_t CIMId, PoIMId, cellInstId, portInstId; axCellInst_t*cellInst; axPortInst_t*portInst; dbObjTypeId_t PoIMType; dbIteratorId_t iterId; stdBoolean_t done;,空行,每个函数定义之间至少空两行 函数分界处除空行外，可以加注释行分割 如 /- / /= 函数内部重要分界处可以空一行,1.4.3 注释,注释的原则 可以不注释就不注释（让代码自己说明） 需要注释一定注释。（关键地方挑明） 注释的类型 行注释 / 块注释 /* */ / 注释风格 比 /*注释风格*/ 好的地方对于多行注释, diff 时能都显示出来. 或者块注释在每行前加 *,注释的场合,文件头 版权 文件（模块）更新历史 文件（模块）重要数据结构和算法概要。 简述数据结构和概要，并说明详尽文档编号。 文件内出现一些缩略语或名词的解释说明 函数说明 函数内部说明,版权,在公司中通常是固定的，放在文件最上面。 在另外一些版权，如GPL 也有些会在项目目录里有个专门的COPYRIGHT文件,/* * ACOMPANY CONFIDENTIAL * * This is an unpublished, proprietary work of ACOMPANY, Inc., and is * fully protected under copyright and trade secret laws. You may not view,* use, disclose, copy, or distribute this file or any information contained * herein except pursuant to a valid written license from ACOMPANY. * */,/* This file is part of the Open Babel project. This is copyright under the GNU General Public License (GPL) For more information, see */,文件信息,/* FILE NAME: sysdep.h* MODULE: System dependencies header* ABSTRACT: This header holds the information programs need to * know concerning O/S, hardware, and other system level thangs.* CONVENTIONS: * Use lower case for all O/S & hardware #defines even if it is*not customary to do so (ie ibm instead of IBM). * COPYRIGHT (C) 1988-1993, ACOMPANY Inc., ALL RIGHTS RESERVED.* COPYRIGHT (C) 1987, OPTIMAL SOLUTIONS INC., ALL RIGHTS RESERVED.*,版本修改历史,简单记录重要改动。尤其是已发布版本的修订版。 处于新建阶段的文件其版本历史可以不记录在这里,HISTORY:=+=+=+=80=90=100= Flag |Author |Update date |Description (project name or star name and description) |=|=|=|=|=|=wjchen0609 wjchen 2006/09/18 09/30 PROJ: 2007.03-MW-LOG-400: DC simplification Something more.wjchen0610 wjchen 2006/10/01 10/30 - detailed description for code change (if necessary): refer to spec.wjchen0609: .f.addddddddddddddddddddddddddddddddddddddddddddddddddddddd sadfassssafsdsd dsdsdsdsds sdsdsdsdsdsdsdsdsdsdsdsdsdsddddddddddddd asfddddddddddddddddddddddddddddddddddddddddddasddddddddddddddddddddwjchen0513: ddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd sadfassssafsdsdsdsdsdsdsdsdsdsdsdsdsdsdsdsdsdsdsdsdsdsddddddddddddd asfddddddddddddddddddddddddddddddddddddddddddasdddddddddddddddddddd,版本修改历史 (cont.),在内部代码更动处加 flag，便于搜索出改动内容,/ wjchen0608: patch 单行patch注释/ wjchen0608 区块patch注释 / wjchen0608,缩略语说明,在本模块或本文件中用到的（如在函数名，变量名等地方）一些缩略语，放在一起，做说明。有利于程序阅读。,LAN: Local Area Network WSN:Wireless Sensor Network,文件结构和算法说明,详细的文件结构和算法说明一般会有专门文档。但很多文档不在代码库中，因此在代码中直接做一个简单解释，有利于快速阅读代码。,我的个人注释风格,函数，模块头注释/*/ 重要模块/,我的个人注释风格 (cont.),/ 2. 第二步/适当使用用 把大函数分割成几块，便于理解和阅读（新型代码阅读器可以展开或收缩花括号）/ 小段解释/ 2.2 /(2.2) / 2)/ wjchen0608: patch,我的个人注释风格 (cont.),用 /XX 表示废弃旧代码，而非一般的说明注释。 用 /XX 表示废弃的说明 用/(_) 表示需要表示需要注意的地方 （像一张睁大眼睛（或带着眼镜）的脸） 或简写作 用/? 表示可能有问题的代码。 /!表示重要说明 用/+ 表示 新增代码,我的个人注释风格 (cont.),/YY 表示该代码被下面的代码替换（Y 像一个箭头 ）如： /YY axGetNetName(cellId, flatNetId, ,我的个人注释风格 (cont.),/+ wjchen: new codes here./+ ,纯粹视觉效果,1. 文件几大功能区分界线 / / PART I. MACRO DEFINIATION / 2. 函数定义分界线。 / - / Function foo. /- 3. 重要函数调用. ret= key_function() /,【总结】注释类别,注释包括1。文件头注释，函数头注释。 版权，创建及修改历史，缩写说明，（函数）参数及返回值说明（如果参数名及函数名可以一望而知，则不必说明以保持简洁）2。关键算法注释（成块） 用一段话表示大体的结构，可以放在文件头或合适的位置。3。函数内代码结构注释。（一段代码） 用三行顿点式构成主要架构4。单句语句注释 通常的注释，用单行，附尾或 /*/ 5。 修订版本标志 /wjchen0607315。废弃代码，替换代码及相关说明。 /XX /YY /XX/YY6。供外部工具使用的特殊标记 如给oxygen提取文档用但标记7。其他标记 /! 特别注意 /? 有问题的代码 /(_):值得注意，可能有问题 （个性化代码，像个睁大眼睛的或带着眼镜的人脸）,废弃代码和被替换代码均为临时保留。如无重要理由，正式代码库中应予以删除。,参考资料,Tao of Coding by Koen Witters （必看） http:/www.chris-lott.org/resources/cstyle/witters_tao_coding.html 林锐，韩永泉 高质量程序设计指南C+/C语言（第三版） 萨特，亚历山德雷斯库 著，刘基诚 译, C+编程规范:101条规则、准则与最佳实践（图灵程序设计丛书） （美）米斯菲尔特，（美）布姆加德纳，（美）格雷 著，罗小平 译, C+ 编程风格(英汉对照),作业,上交一份自己以前做过的项目的源代码。,