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