平常写代码的过程中需要时刻注意代码规范,不仅方便自己也方便他人.由于我平常写代码最常用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.

3、参考资料

3.1 Python风格规范

3.2 C++风格指南

Last modification:August 15th, 2020 at 12:34 am
如果觉得我的文章对你有用,请随意赞赏