无法克服的文件不足
无法克服的文件不足
原文：https://medium.com/hackernoon/insurmountable-documentation-shortfalls-131aa6be7f62
作为软件工程师，我们都有过这样的经历…你会遇到一个庞大的、已建立的代码库，它几乎没有文档。这要么是你自己写的东西，早就忘记了，要么是你被扔进了一个现有的项目，除了几个“这是为了防止世界末日的评论。这是一个真正相关的问题，因为我们都认为我们的代码在编写时是不言自明的，但实际上，如果你 3 个月后再来看，你需要一些指导。在这篇文章中，我将尝试提供一个我过去使用过的可靠方法，在没有文档的地方添加文档，而不会感到不知所措。
工具作业
这里没有必要重新发明轮子。使用你所在的语言生态系统中其他地方正在使用的现代工具。这些工具中的大部分都附带了一些非常有用的输出生成实用程序，可以让您很好地掌握有多少丢失的文档，以及您已经编写了多少。一些例子:
除了格式化输出和标准的明显好处之外，您还将使用其他开发人员能够理解并参与其中的一些东西。
从数据开始，向外移动
我发现从数据模型开始记录系统总是最容易的。这些对象通常非常简单，构成了任何数据驱动应用程序的核心。数据层可以说包含了需要解释的最重要的信息，因为它通常是应用程序其余部分的先决条件。
一旦您在数据层打下了一些高级文档，就从那里向外移动。这可能是服务、控制器、表示等。
忠诚
正如我们在这个领域处理的许多项目一样，它们应该用保真度来定义。你可以把这看作是在开始实现目标之前需要付出的努力和“润色”。例如，如果您正在构建一个登录页面，可能只需要一个用户名和密码字段，而不需要忘记/创建/验证电子邮件功能。类似地(在现实世界中),如果你正在建造一个有形的东西，比如一条路，你可能会在第一次通过时带走泥土或石头，但最终会移动到更永久的东西。在处理绿地文件时，定义你想要的保真度是非常重要的。
就文档而言，这意味着您不需要为每个方法编写完美的中篇小说，用 param 标记和完整的返回声明来完成。从一些不太真实的东西开始:作为一个方法的一两句话，只是为了让大家理解这个观点。随着时间的推移，最复杂的代码区域变得为人所知，您可以通过深入的解释和示例来挖掘更高保真的内容。
新闻报道
类似于从最低层开始向外移动的实践，您也不需要确保每个类或实用程序上的每个方法都有 docs。覆盖那些难以理解的东西，或者包含复杂的逻辑，当你不在状态时，这些逻辑可能不容易理解。不要把时间浪费在编写一个叫做 leftPadWithSixZeros 的方法上，而是花一些时间在像 handleMonthlyBilling 这样的事情上。
同行审查
如果你有幸在一个拥有代码评审过程的团队中工作，那么就把它作为你的文档吧！对你的医生来说，没有什么比确保其他人理解他们更好的了。我所在的团队中，人们会逐字校对您的文档，而我所在的团队中，一行注释只是将方法名重述为一个句子是可以接受的。同行评审在记录文档时会有惊人的帮助，更不用说它可能会给你的工程师同事写一些他们自己的文档的冲动。
总而言之，记录一个被忽视的代码库看起来是一个非常困难的问题。像处理其他任何事情一样处理它，考虑粒度、范围、保真度和工具，它就不会那么糟糕。
最后，当让新人跟上速度时，或者甚至在离开代码一段时间后让自己重新跟上速度时，这将非常有帮助。我已经编写了由几个控制器、服务和存储库组成的最简单的 Spring 应用程序，但是当我离开一段时间后再次使用它们时，我为缺少文档而后悔。
黑客中午是黑客如何开始他们的下午。我们是 @AMI 家庭的一员。我们现在接受投稿，并乐意讨论广告&赞助机会。
要了解更多信息，请阅读我们的“关于”页面、在脸书上点赞/给我们发消息，或者简单地说， tweet/DM @HackerNoon。