Design documents and complex diagrams don't belong in code, but a simple ASCII diagram right there in the code to illustrate how the transformation tree is created:
- is always within easy reach of the eye.
- is harder to forget about when changing the code.
- doesn't require you to download, install, register and fire up Visio Community Edition 2008 to add a new FileLogger node to the illustration of the data transformation tree.
Simple and complex diagrams can be made in any decent graphics app (Inkscape or Keynote are fantastic) and easily exported to PNG or SVG.
Personally I also have a lot of trouble reading ASCII diagrams. Knowing that pipe-slash-dash is a curved line, when the line is broken and the ends don't line up properly.
On a separate note, I suggest whoever moderated me to zero should read the HN guidelines.
- is always within easy reach of the eye.
- is harder to forget about when changing the code.
- doesn't require you to download, install, register and fire up Visio Community Edition 2008 to add a new FileLogger node to the illustration of the data transformation tree.