Reputation: 982

Are ASCII diagrams worth my time?

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)                  |
          |                   |
          |___________________|

Upvotes: 21

Answers (13)

pylover

Reputation: 8065

I love ASCII diagrams anyway. Yes, it is worth it because you can embed them into source code and update them if you use a tool to generate them.

For example, the ADia project aims to save your time by render ASCII diagrams using a human-readable language:

diagram: Foo
sequence:
foo -> bar: Hello World!

Output

 DIAGRAM: Foo                             

 +-----+             +-----+
 | foo |             | bar |
 +-----+             +-----+
    |                   |
    |~~~Hello World!~~~>|
    |                   |
    |<------------------|
    |                   |
 +-----+             +-----+
 | foo |             | bar |
 +-----+             +-----+

Read the documentation or Try the live demo page at github.io: https://pylover.github.io/adia/.

Upvotes: 1

rmeador

Reputation: 25704

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.

Upvotes: 9

anatoly techtonik

Reputation: 20531

I've compiled a list of links and a small tutorial for drawing ASCII diagrams on Python Wiki. Any pictures that save you some time reading the text are definitely worth the time.

Upvotes: 0

lewish

Reputation: 121

You can use http://www.asciiflow.com to draw pretty simple class/flow diagrams and the like. It's entirely web based, using javascript. Chrome/Firefox recommended.

Upvotes: 7

Norman Ramsey

Reputation: 202505

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.

Upvotes: 2

Eclipse

Reputation: 45493

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

Upvotes: 1

jamone

Reputation: 17421

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.

Upvotes: 6

p.marino

Reputation: 6252

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...

Upvotes: 0

Sparky

Reputation: 14057

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.)

Upvotes: 1

Ron

Reputation: 269

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.

Upvotes: 1

Kramii

Reputation: 8419

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

Upvotes: 1

Matt Andrews

Reputation: 2878

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

Upvotes: 1

Tom Cabanski

Reputation: 8018

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.

Upvotes: 6

Are ASCII diagrams worth my time?

Answers (13)

Related Questions