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 常用的几种代码风格,K&R风格 BSD风格 GNU风格 Windows风格 deWiTTERS 风格,1.3 deWiTTERS 风格,deWiTTERS 风格的基本规则有3条： 1）尽量可理解 2）尽量可读，除非与以上规则矛盾 3）尽量简单，除非与以上规则矛盾 反过来说，我们写一段程序要尽量简单，除非影响到了它的可读性和可理解性。 代码风格和具体使用的编程语言有关，但基本规则是不变的。,1.4 代码风格的内容,哪些属于语言定义？哪些属于代码风格？ 正确 vs 规范 标识符的命名规则 变量名、常量名、宏名、函数名、类型名、类名、对象名、方法名 文件名、模块名、项目名 提交安装文件或文档的命名 布局（布白） 缩进 空格，空行 花括号的位置和对齐,注释 版权注释 文件版本历史 文件或模块的功能 函数注释 函数内注释 文件结构和项目结构 一个项目划分成几个文件 文件的组织,1.4.1 标识符的命名规则,标识符 包括标签（label），函数名（function name），宏名，常量名，变量名，宏名，以及文件名，模块名。 1. 用英语，要求准确，简单，专业。 避免拼音，避免容易误解的多义词 2. 根据情况是否用缩写。 用单词的前面部分缩写，可以不必管词性（名词，形容词，动词），单复数，时态等。但有时也可能因此带来不便。,缩写,函数名，变量名不是非常必要缩写的不用缩写。 缩写分为： 1。字头缩写(Acronyms), 宜用大写。如 HECO. _HECO_. 必要情况下可以用小写。如果作为一个很著名的，有明确含义的缩写，如HECO，则用缩写比不用缩写更清楚。 2。长单词缩短：有几个原则： a）通用，如 temp表示 临时，则表示温度时应用全称temperature或 temper b）同一个模块（项目，文件，函数。）应保持一致。 c）7个字母以下的单词通常不缩写。 d）用单词的前一部分 e）用辅音字母。 d和e通常只选择一个。并且以d为好，因为用grep搜索单词的前面部分可以搜索出所有经过和没有经过缩写的单词。,缩写 (cont.),缩写宜遵从约定或惯例。 固定含义的缩写 temp tmp 表示 temporary temporarily 可以用temper表示 temperature com 通常表示 communicate/communication comp （或cmp）表示compare/comparation 函数内部的局部变量（作用范围很小，或者函数很小）可以用缩写，如 index缩写为 idx，count缩写为cnt等。 但对于较长的函数，用全称可能更清楚。,缩写 (cont.),以下为不好的例子： axGetCellInstMasterByName() axuGetPortInstMstByName() 同一个文件中Master既有缩写，又有不缩写的。,全局变量，局部变量，参数,全局变量，局部变量，参数。 标识符包括 标签（label），函数名（function name），宏名，常量名，变量名，宏名，以及文件名，模块名。 变量名有 全局变量，局部变量（函数内部），参数名。 最好在命名时有所区别。 全局变量：尽量避免使用。如果需要，将一个模块内所有全局变量集中在一起。 参数： 需要与局部变量能区分开来，尤其是函数较大的时候。 _IN _OUT _INOUT 局部变量:,变量命名惯例,尽量避免使用 number这个有歧义的词。 序号 index 总数（计数） count 唯一标识 ID 大小 size 长度 length 或 len 但有些固定的用法，比如行号 lineNumber 好像还是 沿用旧例 LineNum 或 LineNo.,变量命名惯例 (cont.),._name 表示字符串类型，不必说明 String flatPortName, flatCIPath, flatCIName, flatNetPath, flatNetName; flatCIPath， 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打头表示member m_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&R风格： if () 以传说中的Kernighan & Ritchie之名命名，因他们的样例代码而被广为接受。又因Unitx内核使用这种风格，所以又被称作Kernel Style，也被它的信徒称作One True Brace Style。也因为C代码主要使用这种风格，也被其他类C语言的使用者称作C风格。这种风格的流行，一是因为大部分教学书籍使用这种风格以节约纸张成本，二是随着Java的普及而被广泛接受。 优点是代码相当紧凑，对低分辨率的显示器和打印文稿来说很有价值； 缺点是在有些情况下匹配大括弧有些困难，并且也因此产生很多子派别。如： if () else 与 if () else ,BSD风格： if () 以Berkeley黑客Eric Allman之名命名，也叫Ansi风格，大括弧独占一行。这是除了K 如果你无法忍受浪费的行，最好的办法就是用这些行来写注释。,GNU风格： if () DoSomething(); 所有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 asfddddddddddddddddddddddddddddddddddddddddddasdddddddddddddddddddd wjchen0513: 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 表示废弃的说明 用/(_) 表示需要表示需要注意的地方 （像一张睁大眼睛（或带着眼镜）的脸） 或简写作 用/? 表示可