Loading... 平常写代码的过程中需要时刻注意代码规范，不仅方便自己也方便他人．由于我平常写代码最常用c++和python，所以在这里我只记录了c++和python代码风格规范．本文主要参考[Google开源项目风格指南](https://zh-google-styleguide.readthedocs.io/en/latest/contents/)． ## 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会将圆括号、中括号中的行隐式地连接起来．因此，如果必要，你可以在表达式外围增加一个额外的圆括号． ```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](http://www.python.org/dev/peps/pep-0394/) , 程序的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, 这一部分可以省略. ```python 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 类 类应该在其定义下有一个用于描述该类的文档字符串. ```python 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 块注释和行注释 最需要写注释的是代码中那些技巧性的部分. 如果你在下次 [代码审查](http://en.wikipedia.org/wiki/Code_review) 的时候必须解释一下, 那么你应该现在就给它写注释. 对于复杂的操作, 应该在其操作开始前写上若干行注释. 对于不是一目了然的代码, 应在其行尾添加注释. ```python # 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风格规范](https://zh-google-styleguide.readthedocs.io/en/latest/google-python-styleguide/python_style_rules/#id1) 3.2 [C++风格指南](https://zh-google-styleguide.readthedocs.io/en/latest/google-cpp-styleguide/) Last modification：August 15th, 2020 at 12:34 am © 允许规范转载