除了写代码我们还得写无数其他东西，我们总是培训要写什么，却很少教大家如何写得好。一句『坑，你懂的』算是什么注释？不光要写，写的有用才有用。见过太多敷衍了事的文档注释各种东西，我发现这问题还挺严重。
什么是好文档的问题，其实是为什么写文档的问题。你写文档的时候，会惦记这些都是为了什么么？
**你为了将来能依赖这些文字还原现场，
在毫无背景的情况下也能看得明白现在做的事情是怎么回事。**
每次提笔的时候都惦记着这个目标，以此作为准则的话，所有那些含糊不清莫名其妙的注释、文档、BUG说明都将不攻自破，你按下确定保存按钮的时候自己都会不安，直到修改得明确无误，详尽全面。
知道为什么才能知道如何做。下次给大家培训开发规范的时候，记得提一下这个。
OH, ONE MORE THING,
拿着这个目标去衡量一遍仓库里的 Commit log，看看有多少是不合格的 ;)
**粗体** _斜体_ [链接](http://example.com) `代码` - 列表 > 引用。你还可以使用@来通知其他用户。