Question

源代码中的ASCII图是否值得他们创建时间？

我可以更快地创建位图图，但是在源文件（until VS2010）中排列图像要困难得多。

为了记录，我不是在谈论decorative ASCII art。

这是我最近为我的代码创建的图表的示例，我可能在MS Paint的一半时间内构建了该图表。

          Scenario A:

                          v
 (U)____________(N)_______<--(P)                   Legend:
          '     /             |                    J = ...
          '    /              |                    P = ...
          '   /d              |                    U = ...
          '  /                |                    v = ...
          ' /                 |                    d = ...
          '/                  |                    N = ...
         (J)                  |
          |                   |
          |___________________|

Answer 1

如果您使用工具从代码生成文档（例如Doxygen），则应该有一种方法可以直接引用图像文件并将其显示在生成的文档中。对于Doxygen，相关命令为\image。这结合了实际图像图表的优点和来自源的易于引用（无需启动像Word这样繁重的程序），以及自动生成的文档。

Answer 2

您可以更好地利用描述变量和函数名称编写清晰简洁的代码，而不需要注释来理解。评论和设计文件都没有编译。结果，它们很快就与代码不同步而变得误导。

Answer 3

你有没有看过那里的各种ASCII艺术转换器？这样你就可以在油漆或其他任何东西中快速绘制，然后让它导出ASCII艺术。

Answer 4

您可以使用http://www.asciiflow.com绘制非常简单的类/流程图等。它完全基于网络，使用javascript。建议使用Chrome / Firefox。

Answer 5

有时，ASCII图确实值得千言万语。但不是经常。我不会去搜索我的所有源文件，但我猜测每20,000行代码的一个图表可能是正确的（或至少不超过两倍）。

任何建议将代码放在一个地方并且图表放在另一个地方的人只是 begging 以使两者变得不一致。最好没有图表或蹩脚的ASCII图表而不是单独的Word文档错误。

Answer 6

试试这个：漂亮的库，用于动态组合这些。 http://code.google.com/p/clojure-textflow/

Answer 7

然后使用MS Paint（或其他）并在源代码管理中包含该图表。

Answer 8

设计文档属于设计文档。为什么没有带有子文件夹的项目文件夹，用于图纸，手册，源代码，示例数据文件，测试用例，愿望清单，更改日志等。我不是说每个文档类型都需要一个单独的目录，但事情应该按逻辑组织

打开外部文件的时间不是浪费时间来制作ASCII艺术品的问题，以及当有人使用不同的编辑器或字体时它会分崩离析的速度。

Answer 9

了解您的受众群体。您的受众（未来的其他开发人员）是否能够使用他们可以使用的工具简单轻松地访问位图？该图有用/有用吗？

代码注释中的ASCII图几乎总是可以轻松查看。（是的，如果使用扩展的ASCII字符，或者开发人员使用的是非固定宽度字体，则可能会出现一些问题。）

Answer 10

您可以让团队中的每个人使用VS2010并将embed actual images放入源文件中。

Answer 11

我同意大多数其他海报：任何不是代码的东西（以及一些评论，但不是太冗长）应该在其他地方，无论是维基还是文档。

由于我过去遭受的各种不幸事件，我宁愿避免使用Word，但这可能是个人偏好。还有一件事：尝试为这些东西设置好名称，并将它们用作代码和文档之间的链接。因此，如果您有一个类（或例程或模块）处理类似您所示的场景的示例，请将其称为SquareBisector或类似的东西，并使其方法为scenarioA（Point a，Point b），scenarioB（Point a，Line l1）等等，然后使用一致的术语在文档中用更多高级术语编写解释它们的文档，并提供大量图表。

请不要在代码中调用您的方法“bisectWithTwoPoints（Point firstPoint，Point secondPoint）”和文档中的“Scenario A”...

Answer 12

我编译了一个链接列表和一个用于在Python Wiki上绘制ASCII图表的小教程。任何能节省你一些时间阅读文字的图片绝对值得花时间。

ASCII图值得我的时间吗？

12 个答案: