好的文档vs.糟糕的文档:不要成为“那种人”

多年来，我们都不得不修改、修复、调试别人的代码。平台各不相同，但挑战是一样的——最大的挑战是，“在#@$!这家伙在想什么?!”看着这个单一的问题——有时是痛苦的，经常是困惑的——让我们想知道它最初是如何发生的。

通常情况下，我们会发现自己处于这种令人困惑的境地，因为文档已经与程序分离了。出现这种情况的原因有很多:

-设备多次易手，信息丢失
-有人认为这是一个通过成为“热门”人物来确保继续就业的机会
-狗吃了
从来没有开发过，因为意图“对任何知道自己在做什么的人来说都是不言而喻的”。
-信息被故意剥夺。

这些只是众多原因中的一小部分。作为开发人员和程序员，我们对前两者无能为力;这只是生活中的一个事实，通常是由我们的最终用户引起的。与此同时，那只讨厌的狗从小学开始就一直挥之不去，而且可能永远不会死。但最后两个原因是我们完全可以控制的。

当我们把一个计划或项目放在一起时，真正完成这项工作是至关重要的。这个完整工作的很大一部分是一个组织良好、文档良好和可维护的系统。该信息与实际代码和配置绑定得越紧密越好。代码越深思熟虑和组织越好。重要的是要记住，无论如何，您可能不是唯一需要处理代码或配置的人。记住你的意思也是个问题。信不信由你，文档和注释在生成第一行代码之前就开始了。

代码和配置注释不必是文学杰作。你不会因为语法和拼写而被评分。最重要的一点是只留下对做了什么和为什么做的解释。使代码内注释部分易于维护，这将鼓励其他人跟随您的领导。如果从一开始就提供注释，那么最近的开发环境通过各种构造使用将信息向前推进，从而帮助文档化过程。

对于那些故意删除评论和不提供文档的人，有一个“特殊的位置”留给了你。除非交付物只是指定为编译后的可执行文件，没有源代码，否则没有任何借口。总得有人在某个地方处理你留下的烂摊子。你唯一的希望就是巫毒娃娃不管用。

最后，无论任何人说什么或做什么，都不能强迫您意识到良好文档的好处。我们都喜欢文档化良好的代码和配置。这终究是一种习得的习惯。只有一种真正的学习经验会改变你的方式，那就是在程序中挖掘并诅咒最初的开发人员，最后才意识到“那个人”就是你自己!

不要成为“那种人”。

本文由Jeff Monforton撰写。杰夫是高级工程师特立独行的技术是一家领先的自动化解决方案提供商，为流程工业提供工业自动化、战略制造和企业集成服务。MAVERICK提供广泛领域的专业知识和咨询，包括工业自动化控制、分布式控制系统、制造执行系统、运营战略、业务流程优化等。

您是否具有本内容中提到的主题的经验和专业知识?你应该考虑为我们的CFE媒体编辑团队做出贡献，并获得你和你的公司应得的认可。点击在这里开始这个过程。