Являются ли диаграммы ASCII достойными моего времени?

Являются ли диаграммы ASCII в исходном коде подходящим временем для создания?

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

Для записи я не говорю об декоративном ASCII-искусстве.

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

          Scenario A:

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

Ответ 1

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

Ответ 2

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

Ответ 3

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

Ответ 4

Вы можете использовать http://www.asciiflow.com, чтобы рисовать довольно простые диаграммы классов/потоков и т.п. Он полностью основан на Интернете, используя javascript. Рекомендуется Chrome/Firefox.

Ответ 5

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

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

Ответ 6

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

Ответ 7

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

Ответ 8

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

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

Ответ 9

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

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

Ответ 10

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

Ответ 11

Я согласен с большинством других плакатов: все, что не является кодом (и немного комментариев, но не слишком подробным), должно быть где-то в другом месте, будь то вики или документ.

Я бы предпочел избегать Word из-за различных неудач, которые я испытал в прошлом, но это может быть личное предпочтение. Еще одна вещь: старайтесь иметь хорошие имена для вещей и использовать их в качестве ссылки между вашим кодом и вашими документами. Поэтому, если у вас есть класс (или подпрограмма или модуль), который имеет дело со сценариями, подобными тем, которые вы показали в качестве примера, пожалуйста, назовите его SquareBisector или что-то вроде этого, и его методы будут иметь сценарий A (Point a, Point b), сценарий B (Point a, Line l1) и т.д., а затем записывать документы, объясняющие их в более высокоуровневых терминах, с большим количеством диаграмм, в документе с использованием согласованной терминологии.

Пожалуйста, не вызывайте свои методы "bisectWithTwoPoints (Point firstPoint, Point secondPoint) в коде и" Сценарий A "в документации...

Ответ 12

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