代码风格规范

平常写代码的过程中需要时刻注意代码规范，不仅方便自己也方便他人．由于我平常写代码最常用c++和python，所以在这里我只记录了c++和python代码风格规范．本文主要参考Google开源项目风格指南．

1、c++代码规范

1.1 命名规范

class_file_name, MyExcitingClass{}, a_local_variable, kConstantName, MyExcitingFunction(),

1.2 注释

1.2.1 文件注释

每个文件都应该包含许可证引用. 为项目选择合适的许可证版本.(比如, Apache 2.0, BSD, LGPL, GPL)

如果你对原始作者的文件做了重大修改, 请考虑删除原作者信息.

如果一个 .h 文件声明了多个概念, 则文件注释应当对文件的内容做一个大致的说明, 同时说明各概念之间的联系. 一个一到两行的文件注释就足够了, 对于每个概念的详细文档应当放在各个概念中, 而不是文件注释中.

不要在 .h 和 .cc 之间复制注释, 这样的注释偏离了注释的实际意义.

1.2.2 类注释

类注释应当为读者理解如何使用与何时使用类提供足够的信息, 同时应当提醒读者在正确使用此类时应当考虑的因素. 如果类有任何同步前提, 请用文档说明. 如果该类的实例可被多线程访问, 要特别注意文档说明多线程环境下相关的规则和常量使用.

如果类的声明和定义分开了(例如分别放在了 .h 和 .cc 文件中), 此时, 描述类用法的注释应当和接口定义放在一起, 描述类的操作和实现的注释应当和实现放在一起.

1.2.3 函数注释

函数声明处的注释描述函数功能; 定义处的注释描述函数实现.

2、Python代码规范

2.1 行长度

每行不超过80个字符

不推荐使用反斜杠\来换行，python会将圆括号、中括号中的行隐式地连接起来．因此，如果必要，你可以在表达式外围增加一个额外的圆括号．

x = ('This will build a very long long '
     'long long long long long long string')

在注释中，如果必要，将长的URL放在一行

2.2 空行

顶级定义之间空两行, 方法定义之间空一行

顶级定义之间空两行, 比如函数或者类定义. 方法定义, 类定义与第一个方法之间, 都应该空一行. 函数或方法中, 某些地方要是你觉得合适, 就空一行.

2.3 空格

括号内不要有空格.

不要在逗号, 分号, 冒号前面加空格, 但应该在它们后面加(除了在行尾).

在二元操作符两边都加上一个空格, 比如赋值(=), 比较(==, <, >, !=, <>, <=, >=, in, not in, is, is not), 布尔(and, or, not).

当’=’用于指示关键字参数或默认参数值时, 不要在其两侧使用空格.

2.4 程序开头`#!`

大部分.py文件不必以#!作为文件的开始. 根据 PEP-394 , 程序的main文件应该以 #!/usr/bin/python2或者 #!/usr/bin/python3开始.

#!先用于帮助内核找到Python解释器, 但是在导入模块时, 将会被忽略. 因此只有被直接执行的文件中才有必要加入#!.

2.5 注释

2.5.1 文件

每个文件应该包含一个许可样板. 根据项目使用的许可(例如, Apache 2.0, BSD, LGPL, GPL), 选择合适的样板.

2.5.2 函数

描述该函数作用

Args: 列出每个参数的名字, 并在名字后使用一个冒号和一个空格, 分隔对该参数的描述.

Returns: 描述返回值的类型和语义. 如果函数返回None, 这一部分可以省略.

def fetch_bigtable_rows(big_table, keys, other_silly_variable=None):
    """Fetches rows from a Bigtable.

    Retrieves rows pertaining to the given keys from the Table instance
    represented by big_table.  Silly things may happen if
    other_silly_variable is not None.

    Args:
        big_table: An open Bigtable Table instance.
        keys: A sequence of strings representing the key of each table row
            to fetch.
        other_silly_variable: Another optional variable, that has a much
            longer name than the other args, and which does nothing.

    Returns:
    """
    pass

2.5.3 类

类应该在其定义下有一个用于描述该类的文档字符串.

class SampleClass(object):
    """Summary of class here.
    Longer class information....

    def __init__(self, likes_spam=False):
        """Inits SampleClass with blah."""
        self.likes_spam = likes_spam
        self.eggs = 0

    def public_method(self):
        """Performs operation blah."""

2.5.4 块注释和行注释

最需要写注释的是代码中那些技巧性的部分. 如果你在下次代码审查的时候必须解释一下, 那么你应该现在就给它写注释. 对于复杂的操作, 应该在其操作开始前写上若干行注释. 对于不是一目了然的代码, 应在其行尾添加注释.

# We use a weighted dictionary search to find out where i is in
# the array.  We extrapolate position based on the largest num
# in the array and the array size and then do binary search to
# get the exact number.

if i & (i-1) == 0:        # True if i is 0 or a power of 2.

2.6 命名规范

module_name, package_name, ClassName, method_name, ExceptionName, function_name, GLOBAL_VAR_NAME, instance_var_name, function_parameter_name, local_var_name.