rainzhaojy / coding_style Goto Github PK

Coding Style:

1. Indent using 4 spaces, do not indent with tabs
2. Only one statement per line
3. No more than 80 characters in one line

Spaces

1. put a space after a keyword
2. put a space after ,
3. do not put a space after the method name
4. put spaces before and after the binary operator
5. do not put spaces before or after the unary operator

Braces

1. put braces after if、for、while、do, etc statements even only one line of code in the code block
2. put the opening brace on the next line of the statement

Good:

for (XM_GROUP_MAP::const_iterator iterGroup = m_mGroup.begin(); iterGroup != m_mGroup.end(); iterGroup++)
{
    // do something
}

Naming convention:

1. In general, use file_name_like_this.h, ClassNameLikeThis, IInterfaceNameLikeThis, StructNameLikeThis, EnumNameLikeThis, methodNameLikeThis, variableNameLikeThis, CONSTANT_VALUES_LIKE_THIS
2. For example: string_helper.h, getPresence(string strBuddyName), onPresenceChanged(), MAX_TEMP_BUDDY_AMOUNT
3. variable name could have MFC style prefix, you are allowed but not recommended to use Hungarian style prefix

MFC style prefix:

Note: no C prefix for class name

Hungarian style prefix:

Abbreviation of Platforms:

1. win - windows, including windows desktop, windows store and windows phone
   • win_desktop
   • win_store
   • win_phone
2. apple
   • apple_mac
   • apple_ios
3. posix - xlinux（mac，android，iOS，linux）
4. android

Miscellaneous:

1. Use OUT to declare an outer param，use IN OUT to declare inter/outer param
2. switch statement must have default block
3. do not use goto
4. do not use Exception，TTI, TR1, you can use C++11

Code Comments style:

Use Doxgen to generate document, the comments follow JavaDoc format, below is a sample:

/**
 * @file string_helper.h
 * @author Dave Zhao
 * @version 1.0
 * @date Nov 9, 2012
 * 
 * Provide some string methods, for example, trim(), find(), replace(), toLower(), format(), etc, 
 * all these methods allow char*, wchar*, string, wstring as parameters
 */

#ifndef __string_helper_h__
#define __string_helper_h__

BEGIN_CCU_NAMESPACE()

namespace str
{
    /**
     * Remove the space charators in the left and right sides of the string
     * @param src the string to be trimmed, if comments is more than one line, you can put in second line, and
     *            align from here
     * @return trimmed string
     */
    template<typename T>
    CCU_FUNC typename strTraits<T>::returnvalue trim(T src)
    {
        return trimLeft(T(trimRight(src)));
    }

    /** one line comment could be like this one */
    template <typename T>
    CCU_FUNC typename strTraits<T>::returnvalue trimLeft(T src)
    {
        ......
    }
}

END_CCU_NAMESPACE()

#endif //__string_helper_h__

Other:

• @deprecated - to declare deprecated methods
• @code ... @Endcode - codes in comments
• @todo - declare todo items
• @see - to refer other classes or methods

Basic Style:

1. tab键由4个空格替代，一般IDE都可以设定
2. 一行代码只做一件事情，如只定义一个变量，或只写一条语句
3. 一行代码不要超过80个字符

Spaces:

1. 关键字之后要留空格，‘，’之后要留空格， 函数名之后不要留空格
2. 二元操作符前后加空格（如赋值操作符、比较操作符、算术操作符）
3. 一元操作符前后不加空格（如“!”、“~”、“++”、“---”、“&”（地址运算符））

Braces:

1. if、for、while、do 等语句自占一行。不论执行语句有多少都要加 {}
2. 程序分界符‘{’和‘}’应独占一行且位于同一列并与引用它们的语句左对齐

Good:

for (XM_GROUP_MAP::const_iterator iterGroup = m_mGroup.begin(); iterGroup != m_mGroup.end(); iterGroup++)
{
    //do something
}

Naming Convention:

1. 文件名 - 全小写，两个单词以下划线连接
   • Good: string_helper.h
2. 类名,struct,enum - 使用"驼峰式"命名，类名前不要加C前缀
   • Good: IBuddyMgr, BuddyMgr
   • Bad: CBuddyMgr
3. 函数名,变量,参数 - 使用"半驼峰式"命名
   • Good: getPresence(string strBuddyName), release()
4. 常量 - 全用大写的字母，用下划线分割单词
   • Good: MAX_TEMP_BUDDY
5. 正向函数名使用动宾结构，回调使用主语加动词过去时
   • Good: setStatus(), onPresenceChanged()
   • Bad: onPresenceChange(), onChangePresence()
6. 变量名和方法名命名要有意义且容易理解，尽量不要使用缩写
   • Good: BuddyMgr* pBuddyMgr; BuddyMgr* m_pBuddyMgr; BuddyMgr* m_pTmpBuddyMgr;
   • Bad: BuddyMgr* pBm; BuddyMgr *m_pBm; BuddyMgr *m_pTmp;
7. 变量建议使用MFC风格前缀，不要求也不禁止使用匈牙利风格前缀

MFC风格前缀:

匈牙利风格前缀:

Abbreviation of Platforms:

平台缩写如下，用于平台相关文件后缀和folder命名:

1. win - windows, 包括 windows desktop, windows store和windows phone，需要细分时可以使用下面的缩写:
   • win_desktop
   • win_store
   • win_phone
2. apple
   • apple_mac
   • apple_ios
3. posix - 表示类linux平台（mac，android，iOS，linux）
4. android

Expression:

1. 不可将布尔变量直接与TRUE、FALSE或者1、0进行比较.
   • Good: if (flag)
   • Bad: if (TRUE == flag)
2. 应当将指针变量用“==”或“!=”与NULL比较.
   • Good: if (NULL != pBuddy)
   • Bad: if (pBuddy)
3. switch必须加 default分支
4. if实现体内如果不是直接return 必须加 else 分支，else里可能只是一个warning log
5. 避免使用 goto 语句
6. 指针删除后必须设为NULL以避免野指针

Function Design Style:

1. 函数参数的书写要完整，不要贪图省事只写参数的类型而省略参数名字
2. 函数入参尽量使用 const 修饰以避免在函数体内被修改，入参尽量用 & 或 * 修饰以减少数据拷贝，譬如 const & 或 const *
3. 函数出参使用宏 OUT 修饰，出入参使用宏 IN OUT 修饰
4. 禁止返回局部变量的指针
5. 函数体不得超过100行，复杂的函数应该被分解为多个子函数

Class Design Style:

1. 尽量将类成员变量声明为 private，外面通过get/set方法访问
2. 禁止直接返回类成员变量的指针
3. 成员变量必须被初始化
4. 将只读型成员函数声明为const函数
5. public/protected/private的顺序遵循原则 - 最希望别人看到的放在最前面
6. 方法和变量不要同时出现在一个public/protected/private声明下面

Miscellaneous:

1. 简单代码原则，尽量不用C ++高级特性，譬如Exception，TTI等，也不要用TR1, C ++11的新特性
2. 简单注释原则，代码是最好的文档，尽量用代码表达作者意图，代码无法解释清楚的才用注释做必要补充，避免废话式注释

CCU specific

1. CCU_API - 所有导出函数使用此声明
2. CCU_CLASS - 所有导出类使用此声明
3. CCU_FUNC - 所有C函数使用此声明，目前被声明为static，将来可以改成inline
4. 关于namespace，所有模块都使用namespace ccu，不要定义自己的namespace，只有string_helper.h使用namespace str

Comments:

代码使用Doxgen注释，注释格式采用JavaDoc格式，下面是一个简单的示例:

/**
 * @file string_helper.h
 * @author Dave Zhao
 * @version 1.0
 * @date Nov 9, 2012
 * 
 * Provide some string methods, for example, trim(), find(), replace(), toLower(), format(), etc, 
 * all these methods allow char*, wchar*, string, wstring as parameters
 */

#ifndef __string_helper_h__
#define __string_helper_h__

BEGIN_CCU_NAMESPACE()

namespace str
{
    /**
     * Remove the space charators in the left and right sides of the string
     * @param src the string to be trimmed, if comments is more than one line, you can put in second line, and
     *            align from here
     * @return trimmed string
     */
    template<typename T>
    CCU_FUNC typename strTraits<T>::returnvalue trim(T src)
    {
        return trimLeft(T(trimRight(src)));
    }

    /** one line comment could like this one */
    template <typename T>
    CCU_FUNC typename strTraits<T>::returnvalue trimLeft(T src)
    {
        ......
    }
}

END_CCU_NAMESPACE()

#endif //__string_helper_h__

关于注释的其他说明:

• @deprecated - 用于说明此方法已不被推荐
• @code ... @Endcode - 写示例代码可以产生代码关键字高亮的效果，并且代码部分会在文档中出现在专门的方框之中
• @todo - 用于说明todo items
• @see - 用于refer其他类或方法