Диаграммы ASCII стоят моего времени?

Question

Стоят ли диаграммы ASCII в исходном коде времени, которое они тратят на создание?

Я мог бы создать растровую диаграмму гораздо быстрее, но изображения в исходном файле намного сложнее ( до VS2010 ).

Кстати, я не говорю о декоративном искусстве ASCII .

Вот пример диаграммы, которую я недавно создал для своего кода, которую я, вероятно, мог бы построить за половину времени в MS Paint.

          Scenario A:

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

Answer 1

Если вы используете инструмент для генерации документации из вашего кода, такой как Doxygen, должен быть способ напрямую ссылаться на файл изображения и отображать его в сгенерированных документах. Для Doxygen соответствующая команда: \ image . Это сочетает в себе преимущества наличия фактической диаграммы изображения с простотой обращения к источнику (не нужно запускать тяжелую программу, такую ​​как Word), а также с автоматически генерируемыми документами.

Answer 2

Ваше время было бы лучше использовать для написания ясного и краткого кода с описательными именами переменных и функций, которые не требуют комментариев для понимания. Ни комментарии, ни проектные документы не компилируются. В результате они быстро не синхронизируются с кодом и вводят в заблуждение.

Answer 3

Вы смотрели различные арт-конвертеры ASCII? Таким образом, вы можете быстро рисовать краской или чем-то еще, а затем экспортировать ASCII-графику.

Answer 4

Вы можете использовать http://www.asciiflow.com для рисования довольно простых диаграмм классов / схем и т.п. Это полностью веб-интерфейс с использованием JavaScript. Рекомендуется Chrome / Firefox.

Answer 5

Иногда диаграмма ASCII действительно стоит тысячи слов. Но не очень часто. Я не буду искать все мои исходные файлы, но я предполагаю, что одна диаграмма на 20 000 строк кода может быть правильной (или, по крайней мере, не более чем в два раза).

Любой, кто предлагает разместить код в одном месте и диаграмму в другом, просто умоляет , чтобы они стали несовместимыми. Лучше не иметь никакой диаграммы или дрянной диаграммы ASCII, чем отдельный неправильный документ Word.

Answer 6

Вы можете заставить всех в вашей команде использовать VS2010 и просто вставить фактические изображения в исходный файл.

Answer 7

Знай свою аудиторию. Сможет ли ваша аудитория (другие разработчики в будущем) получить простой и легкий доступ к растровому изображению с помощью имеющихся в их распоряжении инструментов? Диаграмма полезна / полезна?

Диаграмму ASCII в комментариях к коду почти всегда можно легко просмотреть. (Да, могут быть некоторые проблемы, если используются расширенные символы ASCII или если разработчик использует шрифт нефиксированной ширины.)

Answer 8

Проектная документация относится к проектной документации. Почему бы не иметь папку проекта с подпапками для чертежей, руководств, источника, примеров файлов данных, контрольных примеров, списков пожеланий, журналов изменений и т. Д. Я не говорю, что для каждого типа документов требуется отдельный каталог, но все должно быть организовано логически .

Время открытия внешнего файла не является проблемой, если не считать затраченного времени на создание рисунка ASCII и того, насколько быстро он распадается, когда кто-то использует другой редактор или шрифт.

Answer 9

Затем используйте MS Paint (или любой другой) и включите диаграмму в свой источник управления.

Answer 10

Попробуйте это: хорошая библиотека для динамического соединения. http://code.google.com/p/clojure-textflow/