一、文件排版
1. 包含头文件
- 先系统头文件，后用户头文件
- 只引用需要的头文件
- 系统头文件采用包含子路径方式，自定义头文件应该
2. h和cpp文件
- 文件名用大小写混合 DiyMainVIew.cpp 或者小写混合 infoview.cpp
- 头文件使用 #ifdef 控制块
- 头文件 #endif 使用尾行注释
- 头文件代码块顺序：包含，宏定义，全局变量，全局常量，类型，类，内联部分
- CPP代码块顺序：包含，宏定义全局变量，函数定义
3. 文件结构
- 文件应包含文件头注释和内容
- 函数体、类体之间原则上用2个空行
- 文件头、控制块、包含部分、宏定义、类、全局常量、全局变量、函数函数体间用2空行
二、注释
1. 文件头注释
/*****************************************************************************
* @Description: In User Settings Edit
* @Author: your name
* @Date: 2019-06-05 16:09:00
* @LastEditTime: 2019-06-05 16:09:00
* @LastEditors: your name
*****************************************************************************/
或者以下引例
/*****************************************************************************
* OpenST Basic tool library *
* Copyright (C) 2014 Henry.Wen renhuabest@163.com. *
* *
* This file is part of OST. *
* *
* This program is free software; you can redistribute it and/or modify *
* it under the terms of the GNU General Public License version 3 as *
* published by the Free Software Foundation. *
* *
* You should have received a copy of the GNU General Public License *
* along with OST. If not, see <http://www.gnu.org/licenses/>. *
* *
* Unless required by applicable law or agreed to in writing, software *
* distributed under the License is distributed on an "AS IS" BASIS, *
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. *
* See the License for the specific language governing permissions and *
* limitations under the License. *
* *
* @file Example.h *
* @brief 对文件的简述 *
* Details. *
* *
* @author Henry.Wen *
* @email renhuabest@163.com *
* @version 1.0.0.1(版本号) *
* @date renhuabest@163.com *
* @license GNU General Public License (GPL) *
* *
*----------------------------------------------------------------------------*
* Remark : Description *
*----------------------------------------------------------------------------*
* Change History : *
* <Date> | <Version> | <Author> | <Description> *
*----------------------------------------------------------------------------*
* 2014/01/24 | 1.0.0.1 | Henry.Wen | Create file *
*----------------------------------------------------------------------------*
* *
*****************************************************************************/
2. 函数注释
/**
* @method 方法名
* @for 所属类名
* @param{参数类型}参数名 参数说明
* @return {返回值类型} 返回值说明
*/
以下为常用
// TODO: 待完善
// FIXME: 待优化
// only for DEBUG: 调试代码
// NOTE: 引起关注
@class @callback @param @argument @constructs
@return @returns @author @see @version @requires
@throws @exception @link @author @class
@constructor @type @extends @example @private
@final @event @global @default @module @todo @fixme
例子
/**
* @brief 打开文件
* 文件打开成功后，必须使用::CloseFile函数关闭
* @param[in] fileName 文件名
* @param[in] fileMode 文件模式，可以由以下几个模块组合而成：
* -r读取
* -w 可写
* -a 添加
* -t 文本模式(不能与b联用)
* -b 二进制模式(不能与t联用)
* @return 返回文件编号
* --1表示打开文件失败(生成时:.-1)
* @note文件打开成功后，必须使用::CloseFile函数关闭
* @par 示例:
* @code
* //用文本只读方式打开文件
* int ret = OpenFile("test.txt", "a");
* @endcode
* @see 函数::ReadFile::CloseFile (“::”是指定有连接功能,可以看文档里的CloseFile变成绿,点击它可以跳转到CloseFile.)
* @deprecated由于特殊的原因，这个函数可能会在将来的版本中取消
*/
int OpenFile(const char* fileName, const char* fileMode);
- 对于较大的代码块结尾，如 for|while|do 等加上 // end for|while|do
三、命名
1. 原则
- 同一性：在编写子模块或派生类时，要遵循基类或整体模块的命名风格
- 在保持一个标识符意思明确的同时，应尽量缩短其长度
- 避免出现编号，如 value1, value2
2. TCMR类
- T：简单数据类型，不对资源拥有控制权，析构没有释放动作
- C：表示从CBase继承的类，不能从栈上定义变量，只能从堆上创建
- M：接口类
- R：资源类，系统固有类型，不应在开发代码中出现
3. 函数
AddTableEntry();
OpenFileOrDie(); // 如果出错崩溃加后缀 OrDie
class MyClass {
public:
int num_entries() const { return num_entries_; }
void set_num_entries(int num_entries) {
num_entries_ = num_entries;
}
private:
int num_entries_; // 私有下划线结尾
}
- 函数参数比较多时，应考虑用结构代替
- 如果不能避免函数参数比较多，应每个参数占一行，参数名竖向对齐
4. 变量
- 成员变量：m前缀，如 mBuffer
- 局部变量：指针变量p打头，如 pBuffer，循环变量小写如i,j
- 全局变量：g_ 为前缀
5. 常量
- 全局或类里的常量名称前加k，如 const int kDaysInAWeek = 7;
6. 类型命名