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

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 2

Try this: nice library for putting these together dynamically. http://code.google.com/p/clojure-textflow/

Answer 3

Then use MS Paint (or whatever) and include the diagram in your source control.

Answer 4

Design documentation belongs in a design document. Why not have a project folder with subfolders for drawings, manuals, source, example data files, test cases, wish lists, change logs, etc. I'm not saying that each document type needs a separate directory, but things should be organized logically.

Time to open the external file is not an issue next to the time wasted to make the ASCII art, and how quickly it falls apart when someone uses a different editor or font.

Answer 5

Know your audience. Will your audience (other developers in the future) be able to access the bitmap simply and easily with the tools at their disposal? Is the diagram useful/helpful?

An ASCII diagram in the comments of the code can almost always be viewed easily. (Yes, there may be some issues if the extended ASCII characters were used, or if the developer is using a non-fixed width font.)

Answer 6

I agree with most other posters: anything which is not code (and a bit of comments, but not too verbose) should be somewhere else, be it a wiki or a document.

I'd prefer to avoid Word due to various mishaps I suffered in the past but this could be personal preference. Just one more thing: try to have good names for stuff and use them as a link between your code and your docs. So if you have a class (or a routine, or a module) who deals with scenarios like the one you showed as an example, please call it SquareBisector or something like this, and have its methods be scenarioA(Point a, Point b), scenarioB(Point a, Line l1) and so on, and then write the documents explaining them in more high-level terms, with plenty of diagrams, in a document using a consistent terminology.

Please don't call your methods "bisectWithTwoPoints(Point firstPoint, Point secondPoint) in the code and "Scenario A" in the documentation...

Answer 7

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.

Answer 8

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 9

You could get everyone on your team to Use VS2010 and just embed actual images into the source file.

Answer 10

Sometimes an ASCII diagram really is worth a thousand words. But not very often. I won't go search all my source files, but I'll guess one diagram per 20,000 lines of code might be about right (or at least not off by more than a factor of two).

Anybody who suggests putting the code in one place and the diagram in another is just begging for the two to become inconsistent. Better to have no diagram or a crappy ASCII diagram than a separate Word document that is wrong.