utensil/behind-programming

A book to gather and distill principles, patterns and templates behind programming.

👋 Hi, I'm Utensil

Github is where I explore ideas, write stuff, contribute to or create open-source projects out of personal interest. It's part of my spiritual life, independent of my professional career. I've been coding since my 6th grade (1999), coding connects me with the world: how things work, how I can interact with their internals and build things as how I imagine.

Programming Languages in use:

Programming Languages to learn:

Interests:

behind-programming's Issues

着手编写C++代码规范

• 收集一些相关的链接和点，为正式写C++代码规范做筹备
• 界定代码规范的边界（规定什么，不规定什么，如何处理偏好与一般原则的区别）

补充API设计相关的参考

• https://github.com/Microsoft/api-guidelines

补充C++1x的相关特性的使用说明

基于 https://github.com/AnthonyCalandra/modern-cpp-features

持续补充一些编程规范

• 注释活动应贯穿编码周期始终：先写注释，再写代码，TODO， FIXME
• 说明m_已经明确使得this->不再必要
• 重写RAII段，使之采用acquire/release而非new/delete，避免失去一般性
• 说明一些禁止出现的关键词：如goto、friend
• 整数不再支持i前缀
• 进一步明确*和&要靠近类型
• */
• 显式提及boost mutex guard等
• 构造函数，列表，分组，所有成员，重操作，Init，对于不能在初始化后更改的参数不能提供Set
• 打印日志不能打固定字符串，不要使用perror，不要打印到标准输出端
• 长生命周期的对象，依然要正确实现析构，并说明析构函数的一些坑
• main级别的函数依然应该进行对象化，这样能够规避全局变量
• 介绍什么时候分别使用boost和C++11中同样的函数，兼容性
• 防御式编程，显式提到NULL检查、下标检查，并且提到对assert和异常类的使用
• “目的”一节，进行修订
• 说明为什么使用C++11，以及最有可能使用到的特性
• 说明第三方库的依赖管理原则
• 强调反对定义一个common.h，来间接#include很多头文件，这个会降低编译速度，并且带来不可预料冲突
• 说明头文件包含顺序的意义，以及它和google的保持了一致
• 强调宏用在元编程上，已经do while、_VAR_ARGS_等常见的宏技巧
• 明确反对return Step1() && Step2() && Step3()
• 明确提及public``protected``private顺序
• 函数体内//，增加对于空一格的说明
• 反对throw (errno)
• 通过样例明确m_pfn等
• On而不是SetXXXCallback
• 区分handle和handler
• C++11 lamda function
• boost thread
• if/delete/[]
• log level
• 返回值未必只是判断0
• init idoim
• https://en.wikibooks.org/wiki/C%2B%2B_Programming/Idioms
• https://en.wikibooks.org/wiki/More_C%2B%2B_Idioms
• index用于多个数组，善用sizeof
• http://www.tantalon.com/pete/cppopt/design.htm
• http://neo.dmcs.p.lodz.pl/symos/wyklady/04-TwoPhase.pdf
• && -> || no
• memcpy无法保护两者，strncpy可以
• snprintf sizeof -1
• 不要在if里面调用函数
• 轻函数不做重事；异常不出层次
• char** sizeof(char*)
• enum class
• size_t
• struct no m_
• I for interface
• getter可以不用get开头
• void*优化char*
• ui前缀
• ++i
• 循环的中断位置应留痕
• const
• 关于取时间的代价
• 抛异常的地方，不打印异常日志
• 允许的缩写列表
• 代码处理的对称 ～、Recycle、Release、if、操作、=NULL、调用而不要重复，初始赋值在try外还是在内等
• RAII Guard补充说明：ownership、init负责方、~负责方、action proxy
• 缩略词的大小写方式规定
• 不建议使用///和\param
• 连接超时
• 不同的异常不能混合处理
• LT/ET
• 网络包相关时： u int32 `#pragma pack push
• 模板参数强类型： [ ]
• 避开0，另外0、1、2也不要直接去比较，而应该通过命名常量的方式赋予场景意义
• 序列号唯一性
• 压测报告要在过程中产生，一方面是记录，一方面是反馈并修正
• 进一步强调命名的词性要正确
• 进一步强调不要混合使用异常和布尔返回值
• 说明一些常见的缩写，要当作单词处理，不能全大写：Id、Tcp、Ipc、Cpu等
• 不要使用backtrace等库加重异常
• 明确反对对memcpy_s的使用
• 反对atoi，关键的数字应直接使用字符串比较
• 明确反对数字节的解析方式，而应该使用结构体
• https://github.com/noffle/art-of-readme
• 例外必须是有明文说明、取得共识的规则，而不是例外的事实。
• https://www.zhihu.com/question/35193523/answer/61693305

20160511对C++编码规范的修改建议汇总

• 在changelog一段，同时介绍相关的commit规范和changelog规范，并且强调底线是在合并主干时，正确写好commit log，但同时也建议单独一个文件来维护changelog
• 在文档方面，强调文档的索引
• 简单介绍规范也是为自己服务，提升自己的生产力和效率
• 介绍测试打桩和fixture，以及架子
• 缩进兼容4个空格
• 格式化分basic直接执行，和extra，dry run然后display diff然后prompt for confirmation
• 结构成员的文档注释，允许在行后
• 修改代码时，注意修改对应的注释
• 说明不希望逗号在中间的原因
• 关于如何突出!的问题（语法高亮？）
• 头文件前向声明
• 补充关于同名不同义，同义不同名的说明
• 高危函数处应说明团队应维护自己的高危函数列表（考虑单独文件附一份？）
• 类型命名调整顺序，并区分常见和罕见
• 共享内存 gg_移到争议项
• n加到整数前缀
• p_变为p，移到确定项
• 增加pfn
• 提及结构变量命名的st前缀
• 提及配置项的大小写一致性
• 检查工具中增加valgrind
• 命名中不要用new，要表达语义

着手展开后台架构师意识的指引

部分参考： utensil/utensil.github.io#69

着手组织全书的书写规范

着手组织全书的书写规范，如：

• 本书术语约定
  • 总纲
  • 制度
  • 规范
  • 模式
  • 模版
• 本书写作约定

本issue的目的是收集在书写规范这块的一些先例，作为参考。

确立一个遵循的写作风格指引

如：

http://www.chicagomanualofstyle.org/home.html

https://open.leancloud.cn/copywriting-style-guide.html

https://www.zhihu.com/question/20414919

http://www.ityuedu.com/article/5456678777/

https://docs.google.com/document/d/1R8lMCPf6zCD5KEA8ekZ5knK77iw9J-vJ6vEopPemqZM/edit#/

http://sspai.com/25130?utm_source=qdan.me#/

http://mangatalk.net/2014/typesetting/?utm_source=qdan.me#/

https://github.com/sparanoid/chinese-copywriting-guidelines

http://www.hoowolf.net/2014/12/05/product-copyright-style-guidelines/?utm_source=qdan.me#/

http://www.qdaily.com/articles/1397?utm_source=qdan.me#/

https://qdan.me/list/VLSpNdoDfURWqJ9z

https://gengo.com/wp-content/uploads/2014/02/style-guide-zh.pdf

https://www.zhihu.com/question/22540765

http://www.microsoft.com/Language/zh-cn/StyleGuides.aspx

http://kyc.chzu.edu.cn/s/23/t/1001/dd/4f/info56655.htm

GB/T 9704-2012

https://read.douban.com/reader/ebook/3042635/

收集模式的描述规范的先例

对应急预案，调整表格项的说明方式

目前对对应急预案，说明是在表格内直接做的，其问题有：

• 表格内长度不够，不便于展开，比如多行或者列表
• 部分自明的字段，还需要赘言说明
• 部分公共的字段，反复在各个表格中说明

应调整为：

• 表格项内：给出格式整齐的例子
• 全文、小节最前，或表格前：对共性项的内涵与外延，加以说明
• 表格后：对个性项的内涵与外延，加以说明

补充团队独有规则的样例

团队A:

• F.4 一致地使用4个空格
• F.5 一致地使用“break”风格进行花括号换行
• N.6 函数命名应采用CamelCase的格式，即每个单词的首字母都大写，其他字母小写，单词间直接相连

团队B:

• F.4 一致地使用4个空格
• F.5 一致地使用“break”风格进行花括号换行
• N.6 函数命名应采用camelCase的格式，即第一个单词首字母小写，其余单词首字母大写，其他字母小写，单词间直接相连

补充Makefile约定相关的说明

参考 https://www.gnu.org/software/make/manual/html_node/Implicit-Variables.html 和 http://www.gnu.org/software/autoconf/manual/autoconf.html#Compilers-and-Options

export CC=/data/toolchains/bin/gcc CXX=/data/toolchains/bin/g++ LDFLAGS=-L/data/toolchains/lib64 LD_LIBRARY_PATH=/data/toolchains/lib64:/usr/local/lib/

着手确定好的C++开源代码阅读目标

https://www.zhihu.com/question/21376384

http://coolshell.info/blog/2014/12/c-open-project.html

https://github.com/lk-geimfari/awesomo/blob/master/languages/C_C%2B%2B.md

C:

• https://github.com/nginx/nginx
• https://github.com/libuv/libuv & http://software.schmorp.de/pkg/libev.html
• https://github.com/antirez/redis ( https://github.com/huangz1990/redis-3.0-annotated )
• http://www.sqlite.org/
• http://www.lua.org/

C++:

• https://github.com/google/flatbuffers
• https://github.com/zeromq/libzmq
• https://github.com/google/leveldb & https://github.com/facebook/rocksdb
• https://github.com/bloomberg/bde
• http://loki-lib.sourceforge.net/
• https://github.com/chenshuo/muduo
• http://think-async.com/
• https://github.com/zeux/pugixml
• http://llvm.org/docs/ProgrammersManual.html & http://llvm.org/docs/CodingStandards.html
• https://wiki.qt.io/Get_the_Source
• https://github.com/LippiOuYang/WebBench
• https://github.com/vrogier/ocilib
• https://www.chromium.org/chromium-os/packages/libchrome
• http://www.fastformat.org/
• http://www.pantheios.org/
• https://github.com/facebook/wangle
• https://github.com/facebook/folly
• https://github.com/sass/libsass