docpicture

[bearophileHUGS at lycos.com]

In Python code that processes some geometrical data I want to explain
what each variable like w1, w2, h2, h3, etc, means in the geometrical
objects. In such situation I don't use longer and more clear variable
names because in geometry I'm used to use short vertex/line/length
names, finding them more readable in the various formulas. Complex
formulas full of long names become huge and not much readable anyway.

To explain what those w1, w2, h2, h3 mean I can use text, or sometimes
ASCII art. But ASCII art is very low-resolution, so I have found that
a single little image can explain the meaning of lot of variables (and
other details) in a short space. Leaving the explanations to normal
textual comments.

So in this situation I have sometimes created a quite small image (1
bit/pixel) that encoded in png image format may require just few
hundred bytes. With Python I encode is binary data string in base64,
and I paste that as a string into the Python souce code. It probably
takes only 4-7 lines or so. With one or two more lines of Python I can
decode that string it and save as png again (usually this image
decoding line is commented out or executed only if a debugging global
variable is true). So far I have never used SVG vector images for such
purpose, but they are another possibility (the SVG ones may need to be
bzipped2 before the base64 encoding).

This way there's no risk of losing the essential image, because it's
embedded into the Python code.

Have you ever done this? Do you think such "documentation
picture" (analogous to a docstring) is an acceptable practice? I don't
need to do that often enough, so I think it doesn't deserve to become
supported by Python itself. While I presume emacs and similar
"advanced" editors can be programmed to recognize such string pictures
and show them inlined... :-)

Bye,
bearophile