其他
为什么程序员都不写文档?
(给程序员零距离加星标,了解项目开发.)
作者 | Kislay Verma
译者 | 弯月 责编 | 欧阳姝黎
来源 | CSDN(ID:CSDNnews)
写作从来都不是一件易事。软件工程师与其他人一样,他们不愿意写文档,是因为想要写得条理清晰、简洁明了,实在是太难了。
这就是为什么很多人都在争论在代码中添加注释的价值,以及能作为文档使用的代码的优点。Kevlin Henney认为,在复杂的代码周围添加注释实际上是徒劳的,如果开发人员无法通过代码清楚地表达自己,你又怎么期望他能用英语清楚地表达自己呢?
02
没有文档代码也可以照常发布
即便开发人员不编写文档,他们仍然可以完成自己的工作。没有文档也不会阻碍交付代码(至少不会马上有问题)。没有文档记录的技术决策所造成的损害是累积性的。就像技术负债一样,不会立即造成伤害。
工具
文档该怎么办?
在编写代码之前,首先编写文档。除非代码改动非常小,否则每位工程师都应该写一份注释,说明他们将要进行的工作,并由团队的其他成员来实际执行。经过详尽的讨论后,实际的代码改动就微不足道了。 简化文档的编写工作。不要将文档的编写弄得过于复杂。图表等花里胡哨的东西可以先放一放。你只需要简单地写下你的想法、所做的事情以及原因。即使文档只能为现在和将来的团队其他成员提供基本的说明,也非常有价值。 记录下备选方案。无需详细记录实际的实现(因为实现可能随时间而变化),你应该重点记录选择某个方案的原因。这是代码无法解释的内容,因此记录下来很有价值。你可以根据实际情况,投入一定的时间来记录详细信息。 便于查找。如果人们找不到文档,那么就没有任何用途。你可以使用支持文本搜索的工具。
记录变更。有些组织使用版本控制来记录系统设计随时间推移发生的变更。如果你没有类似的工具,那么请针对每个功能保留一份文档,并在其上不断添加最新的更新信息,以便记录下所有的变更。
- END -
文章精选1、历史上第一个“剁手”的人竟然是...2、女友加班发自拍,男友用几行代码发现惊天秘密...3、嚯!几兆的软件竟有如此强大的功能?4、再见!微软这次彻底放弃了......5、我在大厂,下班了也戴着工牌6、傻瓜式GIF制作工具,以后别再说不会了!7、十多种PDF工具,这个PDF工具箱666!
8、昨天晚上,收到了一封钓鱼邮件!
8、昨天晚上,收到了一封钓鱼邮件!