代码文档——编码之前、之后和过程中

由 Mux 主办的 DEV 全球展示挑战赛：展示你的项目！

有时，你需要为一项更大的任务或新功能做一些设计，你想把你的想法记录下来，也许开始规划代码流程或一些潜在的类，但你会选择哪个应用程序呢？

我经常使用 Google 文档处理个人或工作事务。它操作简便，会自动备份工作内容，而且共享文档或将其转换为其他格式也十分轻松。但是，打开 Google 文档并开始输入伪代码时，自动大小写或代码显示不正常可能会让人感到沮丧。我发现 Code Blocks 扩展程序在这方面非常出色。有了它，在文本旁边插入代码简直轻而易举。

实用技巧——如果您正在使用 Google 文档，您可以更改您的偏好设置，使其不烦人地将句子的首字母大写（这对于喜欢以小写字母开头的 Ruby 类来说相当烦人）。

有时候，你可能只想处理一些小问题，或者分享你在调试某个特别棘手的问题或应用程序某个晦涩部分时所做的研究。对于这类信息，我喜欢使用 Confluence、GitHub 的 README 文件，甚至是 GitHub 的拉取请求 (Pull Request)。具体来说，我会根据内容的性质来决定：是当前正在修复的问题（我会把它放在 GitHub PR 中，如果是 UI 类型的修复，最好附上截图）；是为即将到来的工单或设计工作所做的研究（Confluence 便于分享，也方便其他开发者搜索）；还是代码本身需要的信息，例如元数据或安装信息，README 文件就非常合适。作为一名开发者，我致力于改进我的 Git 提交和 PR，以便更好地进行未来的开发和维护。我强烈建议所有使用 Git 的人都去看看Tekin Süleyman 的精彩演讲“A Branch in Time” 。此外，他关于创建实用 Git 历史记录的博客文章也提供了一些很棒的 Git 技巧，让你认真思考你今天的 Git 注释会如何影响他人明天的代码。

对于 UML 和流程图，我目前首选的应用是LucidChart。它是一款在线图表绘制工具，可以灵活地展示你想要表达的内容。绘制流程图并不难，只需使用常见的形状和线条即可。对我来说，绘制调用 `self.method` 的代码线条是最难的部分，但 LucidChart 提供了一些非常好的教程，可以指导你完成整个过程，并帮助你掌握各种快捷键，让你的工作更轻松。

对于代码本身的文档化，我喜欢编写自文档化的代码。多年来，在编写 Java 代码时，如果你的代码需要添加注释才能让其他开发者理解其功能，那它可能就太复杂了。编写注释并不被鼓励，重构方法和模式以使其更具描述性才是常态。现在，在使用 Ruby 以及我开发的软件时，代码库中出现了更多的注释。代码注释似乎不再像以前那样令人反感。分享如何使用命令对象、API 的用法，或者提供类公共契约的上下文，这些似乎都是内联代码注释的合理用例。我正在逐渐习惯在 Ruby 中有效地使用注释，并且不再将我可能从 Java 中带过来的关于注释的任何偏见带过来。我仍然倾向于将代码重构为更小的块，并使用自描述的方法名，但我明白何时需要代码注释。我所有的方法名都比较冗长，而且我还在努力记住使用蛇形命名法。

作为开发者，我们需要记录的内容非常多，因此找到最适合自己的工具和应用程序至关重要。这样，开发者才能高效地编写代码文档，并希望文档能够方便其他人查找和使用。因为唯一比不编写代码文档更糟糕的情况，就是不使用代码文档。