1 2 34 / 4 页

论坛徽章:: 0

31楼 [报告]

发表于 2013-06-15 10:40 |只看该作者

qq12536767 发表于 2013-06-15 09:40
易刊酒只事格梅座锅答向木锝校沙比

呵呵，中国就这环境

实战分享：从技术角度谈机器学习入门| 【大话IT】RadonDB低门槛向MySQL集群下战书 | ChinaUnix打赏功能已上线！ | 新一代分布式关系型数据库RadonDB知多少？

shan_ghost

小富即安

论坛徽章:: 8

32楼 [报告]

发表于 2013-06-18 10:48 |只看该作者

smalloc 发表于 2013-06-15 10:29

好的文档必须说清楚应该说清楚的；同时，好的文档不应揣测或干涉其他模块的实现——那是其他模块相关文档的职责。

和你的工作实践一样，最令人厌恶的“领导”，是任何地方、只要他觉得“懂”就要插一杠子、但完全不管这一杠子插下去后，后果如何的家伙。

最终，每个工作/每个模块，都少不了他的身影，似乎就他必不可少一样；但实际上，任何疑难、任何需要真正的决策的地方，他都不管——这很容易理解，柿子捡软的捏嘛。

写文档也一样。

不要试图绕开那些需要决策的疑难问题，更不要试图通过东拉西扯来掩盖疑难问题（或者，因为“聊”自己最擅长的东西聊的太起劲，而无意中忽略甚至掩盖了问题）。

比如，之前那个rm -rf的例子：问题出在哪儿呢？

事实上，shell的文档很好：如果命令行有'*'，怎么处理？说的清清楚楚。
rm的文档……怎么说呢，对shell来说，也很好，每个参数的含义，清清楚楚——包括'*'会被shell扩展。

但，用户呢？他需要通过shell去调用rm——开发者们，你们准备给他什么样的体验？

在把关注点放在shell和rm配合上之时，用户体验就被彻底放弃了。这是不应该的；也是喜欢描述“模块之间交互细节”的文档最容易犯的错误。

事实上，rm的文档应该忽略shell，只关注r参数是什么、f参数是什么；然后，自然而然的，由于shell的存在，'*'参数我们没有机会处理，那么万一用户在错误的地方打了'*'、或者类似那个例子，在错误的地方多敲了个空格，怎么办？

当关注点正确时，这个问题就很容易发现和解决：比如，规定当通过命令行传入多个文件/路径时（不管这多个文件/路径是*扩展来的、还是误敲空格多出来的），必须加一个M参数明确说明（激活多目标删除功能），否则就报错退出（就好像不加rf就不能用rm删除目录一样）。

一个简单的rm + shell的'*'扩展就能引出这么多麻烦；那些复杂的、软件内部模块之间的接口，如果关注点都错了，又得闹出多少问题。

比如，如果需要外部调用者辅助维护当前模块的状态（比如申请句柄/归还句柄、开启session/关闭session），那么不要描述外部模块的“正确”流程，而应该明确说明“调用open_session接口开始一个会话；会话结束后，必须调用close_session关闭会话，否则会话将长时间占用资源（直到超时）”。

因为别的模块的实现者未必会照你说的实现；或者，虽然最初设计时的确打算如此实现，但后来因为技术原因而改变了方案（哪怕整个项目都是你一个人做的，这种问题都无可避免）；那么这种流程性描述只能当放屁；最终的代码不乱套才怪。

但，如果你明确要求“open_session必须和close_session配对”，对任何调用者来说，这句话都足够清晰、明确，不会出现歧义，更不怕别人更改实现（管你什么事！）