开发规范V1.0

讯奇 巨力开发规范 广州讯奇数码科技有限公司 汕头市巨力科技有限公司ALL RIGHTS RESERVED 讯奇讯奇 巨力巨力 开发规范开发规范 版本版本 1 0 日期日期 广州讯奇数码科技有限公司广州讯奇数码科技有限公司 汕头市巨力科技有限公司汕头市巨力科技有限公司 版权所有版权所有 不得翻印不得翻印 讯奇 巨力开发规范 广州讯奇数码科技有限公司 汕头市巨力科技有限公司ALL RIGHTS RESERVED 目录目录 修改历史 3 1 C 开发规范 4 1 1 文件夹命名 4 1 2 文件命名 4 1 3 类命名 4 1 4 结构体命名 5 1 5 枚举命名 5 1 6 宏命名 5 1 7 全局函数 5 1 8 静态函数 6 1 9 指针 全局变量 局部静态变量 6 1 10 函数设计 6 1 11 类设计 7 1 12 源代码文件设计 7 1 13 日志规范 8 2 JAVA开发规范 9 2 1 严格遵守 Java 本身的风格 9 2 2 流水日志 9 2 3 性能日志 9 2 4 包设计 9 2 5 类设计 10 2 6 类属性设计 10 2 7 类方法设计 10 2 8 源代码文件设计 10 2 9 关于废代码问题 10 讯奇 巨力开发规范 广州讯奇数码科技有限公司 汕头市巨力科技有限公司ALL RIGHTS RESERVED 修改历史修改历史 时间时间内容内容作者作者 2009 1 22创建本文档梁 兵 讯奇 巨力开发规范 广州讯奇数码科技有限公司 汕头市巨力科技有限公司ALL RIGHTS RESERVED 1 C 开发规范开发规范 1 1 文件夹命名 文件夹命名 采用全小写 多个单词之间直接连接 由于文件夹数量相对比较少 我们使 用一两个单词就可以表达清楚 所以这种命名方式足够了 名称一般要体现名词性 例如 framework webwatch yahoohttp chat163 msnudpfile 1 2 文件命名 文件命名 采用每个单词首字母大写 单词其余部分全小写 多个单词之间直接连接 只有一个单词 首字母也要大写 名称一般要体现名词性 例如 Chat h Chat cpp CommandParser h CommandParser cpp DBQueryPool h DBQueryPool cpp TcpSessionList h TcpSessionList cpp 1 3 类命名 类命名 类名 采用每个单词首字母大写 单词其余部分全小写 多个单词之间直接 连接 只有一个单词 首字母也要大写 与文件名命名相同 名称一般要体现名词性 例如 class Chat class LineReader class CommandParser class DBQueryPool 成员函数名 采用单词首字母大写 多个单词之间直接连接 只有一个单词 首字母也要大写 名称一般要体现动词性 单个动词或动宾结构 例如 class LineReader public int Push void buf int size int GetLine void buf int size int GetLineLen private void MoveData int copyLen private int count int bufIndex int bufSize char pBuf 成员变量名 以下划杠开头 之后部分和成员函数名命名方式一样 例子参 讯奇 巨力开发规范 广州讯奇数码科技有限公司 汕头市巨力科技有限公司ALL RIGHTS RESERVED 见上面代码片段 名称一般要体现名词性 1 4 结构体命名 结构体命名 与 1 3 类名命名相同 名称一般要体现名词性 例如 typedef struct DataTrunk unsigned int type char data 256 void pData struct DataTrunk pNext DataTrunk 1 5 枚举命名 枚举命名 枚举名 与 1 3 类名命名相同 成员名 所有字母大写 各单词之间用下划杠分隔 名称一般要体现名词性 例如 enum DataTrunkType ETHER PKG 0 IP PKG 1 UDP PKG 2 TCP PKG 3 MSG STARTUP 4 MSG SHUTDOWN 5 MSG LOAD 6 MSG UNLOAD 7 TCP STREAM 8 1 6 宏命名 宏命名 所有字母大写 各单词之间用下划杠分隔 名称一般要体现名词性 例如 define IPCHAIN SIZE 64 define PACKDIR OUT 0 define PACKDIR IN 1 define PACKDIR OTHER 2 1 7 全局函数 全局函数 所有字母小写 各单词之间用下划杠分隔 名称一般要体现动宾结构 例如 int init db pool void parse mail char data string 讯奇 巨力开发规范 广州讯奇数码科技有限公司 汕头市巨力科技有限公司ALL RIGHTS RESERVED 1 8 静态函数 静态函数 所有字母小写 各单词之间用下划杠分隔 名称一般要体现动宾结构 记住需要添加 static 关键字 例如 static void process db pool 1 9 指针 全局变量 局部静态变量 指针 全局变量 局部静态变量 全局变量 以小写 g 开头 例如 int gPoolSize 0 char gHostName 128 0 局部静态变量 以小写 s 开头 例如 static int sLoopCount 0 static char sBlackList 256 0 指针类型变量 以小写 p 开头 例如 char pBuf NULL int pBufLen NULL char pBuf 类成员变量 char gpHostName NULL 全局的指针类型 static int spLoopCount 0 静态的指针类型 1 10 函数设计 函数设计 代码行长度 鉴于我们现有的显示器屏幕高度在 45 65 行之间 而宽度在 100 列左右 一个函数体 代码行数原则上控制在 40 行以内 最多不要超过 80 行 也就 是在 vim 编辑器里 大多数函数不用翻屏就能看完 少数函数最多也就上下翻动 一屏 以提高可读性 而一行代码 最长不能超过 90 列 超过了就应该手工分行 注意 函数体应该是一个高内聚的功能体 我们首先应该从它所表达的功能 单元来考虑提取一个函数 函数名应该明确表达其实现的功能 而死死数代码行 数 以为在 80 行以内就是好函数 这是错误的 建议 类成员函数应该短一些 控制在 40 行以内 而全局函数和局部静态 函数 相对于类成员函数 代码行可以长一点 函数参数命名 采用首单词全小写 其余单词首字母大写 多个单词之间直接连接 只有一 个单词 全小写 int readLine void pBuf bool allwaysReturn 函数体内变量命名 如果函数体控制在适当大小 功能高内聚 那么我们不需要定义太多局部变 量 所以临时变量可以采用简单的单词来命名 全部小写 如果实在比较长 则 采用首单词全小写 其余单词首字母大写 多个单词之间直接连接 例如 int i 0 讯奇 巨力开发规范 广州讯奇数码科技有限公司 汕头市巨力科技有限公司ALL RIGHTS RESERVED int len 0 bool flag true int tcpport 80 char pName NULL 花括号对齐 int parse mail if return 0 代码行缩进 代码行要按通常模式缩进 必须使用 tab 来缩进 千万不要使用敲空格来缩 进 因为在用编辑器来阅读时 有人习惯 2 列缩进 而有人习惯 4 列缩进 他们 可以自己设置自己喜欢的缩进方式 动态处理 tab 的显示效果 如果用敲空格来 缩进 就固定死了 例如在 vimrc 里设置 set shiftwidth 4 set tabstop 4 而有些人可能设置 set shiftwidth 2 set tabstop 2 1 11 类设计 类设计 不要设计一个功能大而全的类 类公共接口数控制在 8 个以内 贝尔实验室研究错误率后建议的数量 作者 Martin Fowler 建议的数量 在明确需要提供拷贝构造函数和赋值构造函数时 一定要实现 比如成员变 量有指针 并在构造函数里分配而在析构函数里释放了动态内存时 如果不想提 供 则可以明确 private 化 以免误用值传递 1 12 源代码文件设计 源代码文件设计 头文件 一定要有预编译宏 ifndef SESSION MANAGER H define SESSION MANAGER H 这里声明你的全局函数 类等 endif SESSION MANAGER H 类 结构体 枚举要有功能说明 全局函数 public 型成员函数要有功能说明 最好添加参数说明和返回值说 明 而 private 型则可有可无 函数头的说明 建议采用 doxygen 格式编写 以后可以使用 doxygen 来自动 生成说明文档 讯奇 巨力开发规范 广州讯奇数码科技有限公司 汕头市巨力科技有限公司ALL RIGHTS RESERVED 打开文件 param in pFileName 文件名 param in mode 打开模式 0 读 1 写 2 读写 return 0 成功 1 失败 int open file const char pFileName int mode 源文件 不要乱引用头文件 只保留应该引用的头文件 以减少依赖 加快编译速度 文件行数最多不要超过 500 行 因为平均一个函数控制在 50 行的话 一个 文件里写 10 左右的函数就够多了 用 vim 上下翻动 10 屏以上是很辛苦的 1 13 日志规范日志规范 统一使用公司自己包装的 Log4c 类来写日志 不要使用其它方式写日志 特别是 printf 等屏幕打印 日志格式 类名 成员函数名 日志内容 Log4c Info WebHandle Shutdown start Log4c Info WebHandle Shutdown end 日志级别使用 Fatal 级别 特别严重的错误 如程序崩溃 不常用 Error 级别 错误 一定要写 系统正式运行需要设置这个级别 常用 Warn 级别 警告 一些不属于错误 但需要警告的信息 不常用 Info 级别 普通 主要给开发和测试人员看的流水日志 一定要写 常用 Debug 级别 调试 函数的一进一出 便于调试定位崩溃 死锁 不常用 log4cplus properties 中日志级别设置惯例 系统正式运行 ERROR 级别 测试人员测试 性能测试时使用 ERROR 级别 功能测试时使用 INFO 级别 开发人员测试 性能测试时使用 ERROR 级别 功能测试时使用 INFO 级别 开发人员调试定位崩溃 死锁 DEBUG 级别 由于写日志是频繁的 I O 操作 极其消耗 CPU 而且日志太多了有时反而影 响分析日志 所以要求开发人员在写日志时 一定要分清级别 日志不能多也不 能少 做到恰到好处 日志内容统一使用英文 不要使用中文 1 14 注释注释 不要注释废代码 要直接删除 如果我们要获取以前版本的代码 svn 可以 取到任一版本的代码 讯奇 巨力开发规范 广州讯奇数码科技有限公司 汕头市巨力科技有限公司ALL RIGHTS RESERVED 注释统一使用英文编写 不要使用中文 因为在 unix 环境里使用 vi 编码 不是每个人都喜欢设置中文的 尽量通过函数名来表达整个代码的功能 所以函数要小而功能紧凑 如果你 的函数里需要使用注释来解释一大块代码 那么你应该考虑一下是否应该提 取一个子函数 2 Java 开发规范开发规范 2 1 严格遵守严格遵守 Java 本身的风格本身的风格 因为很多自动工具产生的代码都是采用 Java 本身的风格 所以我们不能另 外自成一套 包括命名规范 编码风格 代码缩进等 2 2 流水日志流水日志 统一使用 Log4J 来写日志 不要使用其它方式写日志 特别是 System 类提供的屏幕打印 日志级别使用 error 错误 一定要写 系统正式运行需要设置这个级别 常用 warn 警告 一些不属于错误 但需要警告的信息 不常用 info 普通 主要给开发和测试人员看的流水日志 一定要写 常用 debug 调试 类方法的一进一出 便于调试定位崩溃 死锁 不常用 log4j properties 中日志级别设置惯例 系统正式运行 ERROR 级别 测试人员测试 性能测试时使用 ERROR 级别 功能测试时使用 INFO 级别 开发人员测试 性能测试时使用 ERROR 级别 功能测试时使用 INFO 级别 开发人员调试定位崩溃 死锁 DEBUG 级别 由于写日志是频繁的 I O 操作 极其消耗 CPU 而且日志太多了有时反而影 响分析日志 所以要求开发人员在写日志时 一定要分清级别 日志不能多也不 能少 做到恰到好处 日志内容统一使用英文 不要使用中文 2 3 性能日志性能日志 统一使用 Perf4J 来写 在数据库访问等可能消耗时间比较长的地方 一定要写 Tag 命名不要太长 但要能明确表达意思 采用 Java 类命名风格 日志内容统一使用英文 不要使用中文 讯奇 巨力开发规范 广州讯奇数码科技有限公司 汕头市巨力科技有限公司ALL RIGHTS RESERVED 2 4 包设计包设计 以功能模块来定义包 包目录下不能太多 Java 文件 以提高可读性 最好不要超过 15 个文件 如果一个包目录下存在太多 Java 文件 一定要定义子包来分解 2 5 类设计类设计 不要设计一个功能大而全的类 功能类 public 方法数控制在 8 个左右 贝尔实验室研究错误率后建议的数 量 作者 Martin Fowler 建议的数量 没有特殊需要 不要使用内部类 匿名类等不常用的语法 以提高可读性 可维护性 降低学习曲线 2 6 类属性设计类属性设计 没有特殊需要 属性一定要定义为私有的 private 或保护的 protected 不能 定义为 public 的 2 7 类方法设计类方法设计 方法名要体现其功能 名称一般要体现动宾结构 代码行数控制在 40 内 要能不滚动屏幕就能看到整个方法实现 列数不要超过 100 列 超过则需要主动分行 2 8 源代码文件设计源代码文件设计 最好一个 java 文件只包含一个 Java 类 一般文件行数最多不要超过 400 行 因为平均一个函数控制在 40 行的话 一 个文件里写 10 左右的函数就够多了 2 9 关于废代码问题关于废代码问题 永远不要通过注释来保留废代码 99 将来不会复原这段代码的 就算需要 我们可以从 svn 取任何一个版本 讯奇 巨力开发规范 广州讯奇数码科技有限公司 汕头市巨力科技有限公司ALL RIGHTS RESERVED 3 开发流程改进开发流程改进 国税数据中心管理平台开发历时两个半月 采用类似瀑布式项目管理方法 原计 划 2010 年 4 月 15 日开发完成 提交给测试和技术支持部门进行集成测试 但集成测 试发现大部分功能模块都存在严重问题 经过 3 周多时间修改 开发人员特别是经验 不足的开发人员 至今没理解正确的业务流程 页面结构设计也不行 典型的情况是 程序是运行正常 但软件功能基本上没考虑用户使用情况 可用性 友好性严重缺乏 业务流程考虑不周 等等 基于这种严重情况 java 开发人员 测试人员 技术支持人员 售前 售后 于 2010 年 5 月 6 日开会讨论问题所在和改进办法 各自提出出现的问题和建议改进方法 瀑布式项目管理模式不适合我们项目情况 特别是业务流程复杂 客户需求随时间有 变化 涉及子系统较多的项目 我们必须采用迭代式 增量式或敏捷项目管理方法来 管理这些项目 3 1 统一业务流程统一业务流程 开发人员测试人员 客户 售前 售后 技术支持人员 项目出资人 客户代理人 开发人员在进行编码之前 必须分析清楚项目的业务流程 特别是重要的业 务流程 开发人员常常自己决定业务处理流程 而最后开发出来的软件不被测试人员 技术支持人员等接受 被迫重新设计和编码 浪费大量时间 要解决这个问题 开发人员在确定业务流程时 自己先分析设计出一个方案 后 必须和测试人员 售前 售后 技术支持人员 项目出资人进行讨论确认 最后大家必须达成一个统一的共识 然后开发人员才能进行编码 开发人员 测试人员常常不能直接面对真实客户 无法了解真实客户的需求 那么我们必须找到客户代理人 客户代理人包括售前