|
|
|
|
@ -2,7 +2,7 @@
|
|
|
|
|
## 前言
|
|
|
|
|
故事还要从前两天我提交的[FileManager](https://github.com/PaddlePaddle/Paddle/pull/2013)的Design Doc PR开始。
|
|
|
|
|
|
|
|
|
|
我肯定是用心写了，我也清楚地记得，提交之前也仔细的检查了(这点自觉性还是有的)，结果，我突然发现，我的PR被Comments刷屏了；这还是其次，更要命的是，当网络速度稍慢的时候会提示我：Comments 太多啦！页面打不开！！哦。简直有点人间惨剧的味道！我要把这些和之前的Comments以及一些典型的Comments总结一下，避免同样的问题，同时也希望对您有用。
|
|
|
|
|
这个文档我肯定是用心写了，我也清楚地记得，提交之前也仔细的检查了(这点自觉性还是有的)，结果，我突然发现，我的PR被Comments刷屏了；这还是其次，更要命的是，当网络速度稍慢的时候会提示我：Comments 太多啦！页面打不开！！哦。简直有点人间惨剧的味道！我要把这些和之前的Comments以及一些典型的Comments总结一下，避免同样的问题，同时也希望对您有用。
|
|
|
|
|
|
|
|
|
|
我觉得里边有几个基本的原则：
|
|
|
|
|
|
|
|
|
|
@ -103,18 +103,18 @@
|
|
|
|
|
应该都是陈述句的描述。有不确定的问题可以提Issue来讨论获得结论。
|
|
|
|
|
对于自己不确定的地方，与其含混而过不如找人讨论先搞一个靠谱的可以讨论的。绝大多数情况下，这种含混而过的都会被Reivew给纠出来。即便就不出来，岂不是自己给自己埋一个坑？
|
|
|
|
|
|
|
|
|
|
- 文档当中不要黏贴大量的代码
|
|
|
|
|
- 文档当中不要黏贴大量的代码
|
|
|
|
|
代码一般都是细节，改变的非常的快，文档可能很快就失效了，需要重新的修正。另外，最主要的是大段的代码会让人的思路中断，陷于实现的细节当中。
|
|
|
|
|
|
|
|
|
|
- 不准备实现的就不要写了
|
|
|
|
|
- 不准备实现的就不要写了
|
|
|
|
|
最多放到放到`Future`中展望一下。
|
|
|
|
|
|
|
|
|
|
## 文笔要好
|
|
|
|
|
啊呀，不想当作家的程序员不是好程序员。这个当然比较难，要看大家的“学好数理化，走遍天下都不怕”的基本功的“深厚”程度了：）
|
|
|
|
|
|
|
|
|
|
推荐一下公众号：老万故事会[link](https://freewechat.com/profile/MzI1MDQ3NTAxOQ==)，一个文章和代码写的一样好的人<sup>[yi](#yi)</sup>。
|
|
|
|
|
顺便推荐一下公众号：老万故事会[link](https://freewechat.com/profile/MzI1MDQ3NTAxOQ==)，一个文章和代码写的一样好的人<sup>[yi](#yi)</sup>。
|
|
|
|
|
|
|
|
|
|
## 参考资料
|
|
|
|
|
## 参考
|
|
|
|
|
- <a name=yi>WangYi</a>
|
|
|
|
|
- <a name=WuYi>WuYi</a>
|
|
|
|
|
- <a name=Helin>Helin</a>
|
|
|
|
|
|
gongweibao
9 years ago