$ ls ~yifei/notes/

代码风格指引

Posted on:

Last modified:

代码要做到 自文档化

Python

  • util 模块使用 util.py(单数形式),而不是 utils.py,因为 python 标准库使用的是 util
  • 模块的命名:如果只有一个类,比如 ItemProcessor,那么可以命名为 item_processor.py,否则不能使用名词命名,使用描述性的短语『名词+动词』

django

  • 使用 queryset 的时候尽量使用 .only(),以减少对数据库的压力

devops

  • using mosh is recommended over plain ssh
  • using tmux is recommended over screen
  • all directories/repositories should use underscore NOT hyphen
  • 应该使用 json schema 来验证 json 是否合规
  • 每一个调用方都应该使用 token 或者 caller 来表明自己的身份,拒绝任何没有声明身份的服务。而生成 token 应该使用库来实现,而不是服务,以避免所有的服务都依赖 token 检测。

coding

  • 变量跨越的行数太多,否则不能看懂其中变量的用途,尽量是变量的生存周期短
  • 函数不能写太多行(20 行以内为宜,最多 40 行),不然读起来太费劲了,根本不知道是什么函数,如果太长,需要拆分
  • 不要去变换 API 的签名,如果需要更改,做一个新的版本
  • 如果没有很好的名字,使用 ret 作为返回值的名称
  • 如果协议容易出现问题,那么在 thrift 中增加一个字 version,每次校验是否是同一个版本
  • variable names should use simple words if possible
  • 不要起名字相同的函数
  • 常量的定义,要把每个维度正交化,使用每个位来表示一个开关,或者几个位来表示一个组合

思维

  • 如果在编码实现的过程中发现实际情况更加复杂,也不要直接改变思路,先实现原先想好的简单情况,在做拓展
  • 类应该是 sans-IO 的,如果需要 IO,就写一些 load 函数,但是不要在构造函数中调用

Indent, spaces and newline

  • use spaces around + - * / = ==
  • use spaces only after , ;
  • one blank line between functions and two between classes
  • use \n as line endings
  • end file with a new line
  • always use 4 spaces to indent
  • always use K&R braces

Naming and variables

  • never use HN but prefix is for bool flags or methods e.g. is_open
  • use CamelCase for class name
  • use camelCase or snake_case for function, variable, method name, just be consistent
  • declare local variable as late as possible
  • use nullptr not NULL

Headers

  • header file should use *.hpp NOT *.h
  • always use #define guards
  • Reduce the number of #include files in header files. It will reduce build times. Instead, put include files in source code files and use forward declarations in header files. If a class in a header file does not need to know the size of a data member class or does not need to use the class's members then forward declare the class instead of including the file with #include. To avoid the need of a full class declaration, use references (or pointers) and forward declare the class.

Namespaces

  • never use using namespace std

其他

  • put a space after if for while so that we know it's not invokation
  • never use if (someVar == true) or if (someVar == false), it's silly

Documnetation and comments

  • Documentations explain how to use code, and are for the users of your code
  • Comments explain why, and are for the maintainers of your code
  • use javadoc for documentations
  • use FIX BUG TODO ??? !!! to show different kinds of comments

日期与时间

Always use timezone-aware time or timestamp, never use local time string.

Python docstring

使用 Google 的 docstring 规范

django

  • 在 admin 后台自定义属性的时候,函数要加一个下划线后缀,以便和模型的属性区分

注释

要写成一个句子,不能写成不完整的一个短语。

变量名

英文:使用简洁易懂的英文,不要使用复杂的。例子:使用 copycat, 不使用 Plagiarism

产品名:对于国内产品,使用拼音,不使用英文名。例子:使用 weixin,不使用 wechat。

公司名:使用英文,不使用中文。例子:使用 tencent,不使用 tengxun

数量一律使用 num_something 命名。布尔值使用 is_adj(形容词) 或者 done 表示

  • never use HN but prefix is for bool flags or methods e.g. is_open
  • declare local variable as late as possible
  • use nullptr not NULL

流程控制

符合预期的异常必须捕获。未捕获的异常必须表示某种未知的错误。

Python

禁止在代码中修改 PYTHONPATH

禁止直接连接服务,必须使用连接池,连接使用完毕之后放回到连接池。

严禁使用 kwargs

代码管理

采用 Google 的分支管理方式,所有人在主分支上开发,有功能则切出来新分支,但是合并的时候必须压缩,发布切单独的分支出来。https://trunkbaseddevelopment.com/

每一行日志都应该有对应的监控。

服务连接尽量使用 dsn 方式,不然太麻烦了。

Headers

  • header file should use *.hpp NOT *.h
  • always use #define guards
  • Reduce the number of #include files in header files. It will reduce build times. Instead, put include files in source code files and use forward declarations in header files. If a class in a header file does not need to know the size of a data member class or does not need to use the class's members then forward declare the class instead of including the file with #include. To avoid the need of a full class declaration, use references (or pointers) and forward declare the class.

Namespaces

  • never use using namespace std

Others

  • put a space after if for while so that we know it's not invokation
  • never use if (someVar == true) or if (someVar == false), it's silly

Documnetation and comments

  • Documentations explain how to use code, and are for the users of your code
  • Comments explain why, and are for the maintainers of your code
  • use javadoc for documentations
  • use FIX BUG TODO ??? !!! to show different kinds of comments

参考

  1. http://python.net/~goodger/projects/pycon/2007/idiomatic/handout.html
  2. http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml
  3. https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Coding_Style
  4. http://www.yolinux.com/TUTORIALS/LinuxTutorialC++CodingStyle.html
  5. http://python.net/~goodger/projects/pycon/2007/idiomatic/handout.html
  6. http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml
  7. https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Coding_Style
  8. http://www.yolinux.com/TUTORIALS/LinuxTutorialC++CodingStyle.html
  9. https://stackoverflow.com/questions/3898572/what-is-the-standard-python-docstring-format
  10. https://nedbatchelder.com/blog/201401/comments_should_be_sentences.html

© 2016-2022 Yifei Kong. Powered by ynotes

All contents are under the CC-BY-NC-SA license, if not otherwise specified.

Opinions expressed here are solely my own and do not express the views or opinions of my employer.