Are ASCII diagrams worth my time?

Question

Are ASCII diagrams within source code worth the time they take to create?

I could create a bitmap diagram much faster, but images are much more difficult to in line in a source file (until VS2010).

For the record, I'm not talking about decorative ASCII art.

Here's an example of a diagram I recently created for my code that I probably could have constructed in half the time in MS Paint.

          Scenario A:

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

Answer 1

If you use a tool to generate documentation from your code, such as Doxygen, there should be a way to reference an image file directly and have it appear in the generated docs. For Doxygen, the relevant command is \image. This combines the benefits of having an actual image diagram with ease of reference from the source (no need to fire up a heavy program like Word), and also with your auto-generated docs.

Answer 2

Your time would be better utilized writing clear and concise code with descriptive variable and function names that does not require comments to understand. Neither comments nor design documents compile. As a result, they quickly fall out of sync with the code and become misleading.

Answer 3

Have you looked into the various ASCII art converters out there? That way you can draw quickly in paint or whatever and then have it export ASCII art.