Stag-Java快速上手指南.docx

Stag-Java快速上手指南深圳市施泰信息技术有限公司Stag Java快速上手指南Stag Java Coding Quick GuideVersion 1.0Kim Shieh2014/9/12编程不是艺术，而是一项工程活动。对于任何工程项目来说，统一的施工标准都是保证工程质量的重要因素。高品质、易维护的软件开发离不开清晰明确的编码规范。修订历史修改人修改内容时间版本号Kim Shieh起草、编写2014.9.13Ver 1.0目 录1概述31.1书籍推荐32命名约定42.1文件和目录42.2代码43代码风格与版式64注释74.1普通注释74.2文档化注释81 概述本指南根据Stag-Java编码规范内容，抽离出具体的代码模板并加以点评，以帮助新同事快速熟悉主要的编码规范点，以便尽快地投入到项目中。本指南仅仅是编码规范的一个子集，侧重于代码的风格和版式。更多为了避免深层次的Bug而推出的编程习惯、技巧和规则，请参考完整的Stag-Java编码规范。1.1 书籍推荐下面列出一些评价非常高的著作，对于高质量编程具体非凡的指导意义，希望大家在紧张的工作中，抽出一些时间进行学习、积累和沉淀：l Java编程思想（关注怎样编程）l 代码大全（编程经验积累）l 编程之美：微软技术面试心得（关注有趣算法）l 设计模式：可复用面向对象软件的基础（关注设计和架构）l 敏捷软件开发：原则、模式与实践（关注项目过程）l 人月神话（关注项目管理）2 命名约定2.1 包包名全部采用小写字母，包名中不能出现下划线，并且第一个字母不能是数字。2.2 代码文件：DscpDevice.h使用 #define 防止头文件被多重包含。格式：_H_#ifndef DSCP_DEVICE_DSCP_DEVICE_H_#define DSCP_DEVICE_DSCP_DEVICE_H_#include Common/Types.h使用相对于项目根目录的相对路径。路径分隔符使用 / ，而不是 避免使用绝对路径，避免使用 . 或 .#include DncpStack/DncpStack.h#include DNCP/App/DscpController.h#include DscpMonitor.h#include DscpMsg.h/* * brief DSCP 设备对象，用于操作指定的一个设备。 * note 本节点基于DNCP的TRP路由协议，通信之前不建立连接。类型名称都使用PascalCase风格，包括：类、结构/联合体、枚举、名字空间、typedef等 */class DscpDevicepublic: DscpDevice(Uint8 d1, Uint8 d2, Uint8 d3 = 0, Uint8 d4 = 0); DscpDevice(void);方法名称使用PascalCase风格，按业务功能命名，使用有意义的动词或动宾短语public: void SetTimeout(int millisecond);public: bool Send(Uint16 cmdCode, void* data = NULL, Uint16 len = 0);变量名采用camelCase风格，除了第一个单词外，所有单词首字母大写 DscpResp ExpectResp(Uint16 respCode); Uint16 ExpectStatus(Uint16 respCode); DscpEvent ExpectEvent(Uint16 eventCode);类成员变量使用m_ 前缀；全局变量使用 g_ 前缀；静态变量使用 s_ 前缀；private: DeviceAddress m_deviceAddress; int m_timeout; ;#endif / DSCP_DEVICE_DSCP_DEVICE_H_文件：DscpDevice.cpp#include DscpDevice.h宏和枚举值的命名采用UPPER_CASE风格，即所有字母都大写，单词之间使用下划线分隔。#define DEVICE_PORT_NUM 12enum AlternateUrlTableErrors OK, OUT_OF_MEMORY, MALFORMED_INPUT,常量名称采用camelCase风格，但应使用常量前缀k；常量命名不使用类型前缀，通常也不使用范围前缀;const int kDaysInAWeek = 7;/*变量不使用类型前缀，也不使用指针前缀。错例：uiCmdCode、pData、szText * brief 发送命令到设备，阻塞调用。 * paramin cmdCode 命令码。 * paramin data 参数数据指针，缺省为NULL。 * paramin len 参数数据长度，缺省为0。 * return 命令是否成功发送出去。 */bool DscpDevice:Send(Uint16 cmdCode, void* data /*= NULL*/, Uint16 len /*= 0*/)变量命名可以使用一些约定俗成的缩写，常用的缩写如：l idx 索引indexl cnt 计数 countl str 字符串 stringl param 参数 parameterl len 长度 lengthl num 数量 numberl info 信息 information return (TRUE = DncpStack_Send(m_deviceAddress, cmdCode, data, len);Uint16 DscpDevice:ExpectStatus(Uint16 respCode) Uint16 status = DSCP_TIMEOUT;bool isBusy; / . if (isBusy) 布尔变量可以使用is/has/need作为前缀，可读性更好。 / . return status;3 代码风格与版式void DscpDevice:SetupRfid(int num)代码块（函数体、if/for/ switch/class/try/catch等）的左括号独立为新行，并且与起头语句左对齐int i;for (i = 0; i GetResp(m_deviceAddress, respCode, RESP_STATUS); if (resp) 语句中适应使用空格。关键字与左括号之间、二元操作符前后、逗号和分号之后应该加一个空格；函数名之后、一元操作符与主体之间、成员引用符两边不应加空格； break; System_Sleep(TRY_INTERVAL); if (resp) 对于if、for、while、do、try、catch 等代码块，即使只有一条语句，也应该使用大括号括起来 if (resp-data != NULL) status = *(Uint16*)resp-data); 一行代码只做一件事情，如只定义一个变量、只写一条语句。下面代码是不可接受的：int i, num, triggerCounter;while (i != 0) CheckRound(i-);num+ *= i -= triggerCounter + 5;int num;int count; return status;4 注释4.1 普通注释Uint16 DscpDevice:ExpectStatus(Uint16 respCode)普通注释不要使用C风格的注释 /* 文件已经打开 */ if (isOpen)注释符与内容之间无空格；加上空格要优雅得多； /要删除的文件数目 / 要删除的文件数目 numFile+; / 超时处理，在指定的时间内仍没有回应则返回超时状态注释应当准确、简洁、易懂，防止注释有二义性。 int tryTimes = m_timeout / TRY_INTERVAL; while (tryTimes-) resp = m_recvMonitor-GetResp(m_deviceAddress, respCode, RESP_STATUS); if (resp) break;注释可以放在代码的上方或右方，不可放在下方。 System_Sleep(TRY_INTERVAL); 代码右方的注释只适合简短的注释，如果注释内容较多，必须放在代码的上方。 / 接收到的字符数目int num; / 接收到的字符数目这种注释通常是不必要的，还不如把变量名字命名得更有意义点，如numOfReceivedChars，让代码自“注释” / todo (Kim) 未在命令表中找到命令时，需要特殊处理。for (int i = 0; i sizeof(cmdTable); i+)使用todo、bug等标记标注代码，让IDE和Doxygen帮助管理这些待办事项。 . /* * bug () 多次失败的操作会引发内存泄漏，需要特殊处理。 */注意标点，拼写和语法，中文注释使用中文标点。注释中既有中文又有英文时，中文与英文之间用空格隔开。return RESP_STATUS;4.2 文档化注释Doxygen支持好几种注释风格，如JavaDoc风格、QT风格、C+风格等。考虑到IDE的广泛支持（Eclipse CDT），我们使用JavaDoc的注释风格。文档化注释应放在元素定义或实现处，而不是声明处；应放在源文件中，而不是头文件中。对外接口元素（如类、宏、全局变量、公共函数等）必须注释，而且必须使用文档化注释。4.2.1 类注释模板/* * brief 提供对MyGraph中所有图形元素公共特性的抽象。 * details * 具备可显示，可移动等特征的图形基类，所有其他的图形元素都派生自该类型。 * MyGraph的用户多数情况下都会使用那些具体的Shape派生类，而不是Shape。 * * 当调用 ref Shape:Shape 构造函数创建出一个图形对象时， * 该对象并不会马上显示到显示设备上，而是需要调用该对象的 ref Draw * 方法后图形才会得以显示。不过需要注意的是， ref Draw方法只是负责将 * 图形的最新状态绘制出来，并不负责清除这个图形上一次在显示设备上的残留 * 图像。因此在大多数情况下，你可能都需要首先调用 ref Device:Clean * 方法进行清除操作。 * * * invariant 无论在任何情况下，图形必然不会超出 * (-1600, -1600, 1600, 1600)这一范围不变项是可选的，根据实际需要选用 */class Shape4.2.2 函数注释模板/* * brief 移动图形到参数指定的位置并返回指示移动成功与否的标志 * details 图形移动到参数指定的矩形区域中后，还将根据目标矩形的大小进行拉伸，需要指明参数方向 * 注意调用moveTo并不会马上引发图形的重绘，如果希望显示图形移动后的