utensil/behind-programming

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

behind-programming's Issues

补充团队独有规则的样例

团队A:

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

团队B:

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

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

如：

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/

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

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

补充API设计相关的参考

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

着手编写C++代码规范

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

持续补充一些编程规范

• 注释活动应贯穿编码周期始终：先写注释，再写代码，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

着手确定好的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

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，要表达语义

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

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

着手组织全书的书写规范

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

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

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

补充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/

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

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

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

应调整为：

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

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