$ ls ~yifei/notes/

逸飞的代码风格指引

Posted on:

Last modified:

生产环境,禁用元编程等花哨的特性

Naming and variables

  • 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
  • 使用简洁易懂的英文,不要使用复杂的。例子:使用 copycat,不使用 plagiarism
  • 产品名:对于国内产品,使用拼音,不使用英文名。例子:使用 weixin,不使用 wechat。
  • 公司名:使用英文,不使用中文。例子:使用 tencent,不使用 tengxun
  • 不要起名字相同的函数
  • 常量的定义,要把每个维度正交化,使用每个位来表示一个开关,或者几个位来表示一个组合
  • 数量使用 num_something 命名。布尔值使用 is_adj(形容词)或者 done/ok 表示
  • 如果没有很好的名字,使用 ret 作为返回值的名称

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
  • put a space after if for while so that we know it's not invocation

coding

  • 变量跨越的行数太多,否则不能看懂其中变量的用途,尽量是变量的生存周期短
  • 函数不能写太多行(20 行以内为宜,最多 40 行),不然读起来太费劲了,如果太长,拆分
  • 不要去变换 API 的签名,如果需要更改,做一个新的版本
  • API 要有版本
  • 注释要写成一个句子,不能写成不完整的一个短语。
  • Never use if (someVar == true) or if (someVar == false), it's silly
  • 流程控制,符合预期的异常必须捕获。未捕获的异常必须表示某种未知的错误。
  • 服务连接尽量使用 dsn 方式,不然太麻烦了。
  • 如果在实现的过程中发现实际情况更加复杂,不要直接推倒重来,先实现原先的简单情况,再拓展
  • 类应该是 sans-IO 的,如果需要 IO,就写一些 load 函数,但是不要在构造函数中调用

Documentation 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 self-documentations
  • use FIX BUG TODO to show different kinds of comments

Python

  • Always use timezone-aware time or timestamp, never use local time string.
  • 使用 Google 的 docstring 规范
  • 禁止在代码中 import sys.path 来修改 PYTHONPATH
  • 禁止直接连接服务,必须使用连接池,连接使用完毕之后放回到连接池。
  • 严禁使用 kwargs

C++

  • 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.
  • Never use using namespace std
  • use nullptr not NULL

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 来表明自己的身份,以便能及时降级
  • 服务不应该重复开发,应该最好收敛到一套,统一提供服务,但是对不同的业务要分开部署,做好隔离,避免造成单点依赖。
  • 有人工编辑的字段不要直接写到某个字段上,会被覆盖,要再添加一个字段 v_xxx

不要过早优化

就像我小时候穿的衣服,我妈总给我买大一号的,可我的生长速度没那么快,每次都是穿烂了都还大。 现在轮到我女儿了,姥姥奶奶再给买衣服,我都是让她们直接买正好的就行。

内部的过度设计有两个结果:一些设计根本不可能用上,另一些等到用上的时候,发现当初设计的时候 考虑不全,还不能用,正所谓半吊子。

永远不要做无意义的抽象,抽象是有成本的,所以必须要有收益才值得这么做。

并行化是一项很耗费脑力的性能优化,尽量减少并行代码,只在必要的地方加。

参考

  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
  11. 不好的代码是什么样的
  12. https://zhuanlan.zhihu.com/p/34982747
  13. https://www.zhihu.com/question/24282796/answer/139789668
  14. https://opensoul.org/2011/11/30/haml-the-unforgivable-sin/
  15. https://web.archive.org/web/20220607054703/http://journal.stuffwithstuff.com/2016/06/16/long-names-are-long/
WeChat Qr Code

© 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.

友情链接: MySQL 教程站