Являются ли диаграммы ASCII в исходном коде подходящим временем для создания?
Я мог бы создать растровую диаграмму намного быстрее, но изображения намного сложнее в строке в исходном файле (до VS2010).
Для записи я не говорю об декоративном ASCII-искусстве.
Вот пример диаграммы, которую я недавно создал для моего кода, который я, вероятно, мог бы построить за половину времени в MS Paint.
Scenario A:
v
(U)____________(N)_______<--(P) Legend:
' / | J = ...
' / | P = ...
' /d | U = ...
' / | v = ...
' / | d = ...
'/ | N = ...
(J) |
| |
|___________________|
Если вы используете инструмент для создания документации из вашего кода, например Doxygen, должен быть способ напрямую ссылаться на файл изображения и отображать его в сгенерированных документах. Для Doxygen соответствующая команда \image. Это сочетает в себе преимущества наличия фактической графической диаграммы с простотой ссылки от источника (нет необходимости запускать тяжелую программу, например Word), а также с вашими автоматически генерируемыми документами.
Ваше время было бы лучше использовать четкий и сжатый код с описательными именами переменных и функций, которые не требуют комментариев для понимания. Компиляция комментариев и проектных документов не выполняется. В результате они быстро теряют синхронизацию с кодом и вводят в заблуждение.
Просматривали ли вы различные конвертеры искусства ASCII? Таким образом, вы можете быстро рисовать краску или что угодно, а затем экспортировать ASCII-искусство.
Вы можете использовать http://www.asciiflow.com, чтобы рисовать довольно простые диаграммы классов/потоков и т.п. Он полностью основан на Интернете, используя javascript. Рекомендуется Chrome/Firefox.
Иногда диаграмма ASCII действительно стоит тысячи слов. Но не очень часто. Я не буду искать все мои исходные файлы, но я угадаю, что одна диаграмма на 20 000 строк кода может быть оправа (или, по крайней мере, не выключена более чем в два раза).
Любой, кто предлагает поставить код в одном месте, а диаграмма в другом - просто попросить двух, чтобы они стали непоследовательными. Лучше не иметь диаграммы или дрянной ASCII-диаграммы, чем отдельный документ Word, который является неправильным.
Попробуйте это: хорошая библиотека для динамического их объединения. http://code.google.com/p/clojure-textflow/
Затем используйте MS Paint (или что-то еще) и включите диаграмму в свой исходный элемент управления.
Проектная документация принадлежит проектной документации. Почему бы не создать папку проекта с вложенными папками для чертежей, руководств, исходных файлов примеров данных, тестовых примеров, списков пожеланий, журналов изменений и т.д. Я не говорю, что каждому типу документа нужен отдельный каталог, но все должно быть организовано логически.
Время открытия внешнего файла не является проблемой рядом с временем, потраченным впустую, чтобы сделать искусство ASCII, и как быстро оно разваливается, когда кто-то использует другой редактор или шрифт.
Знай свою аудиторию. Будет ли ваша аудитория (другие разработчики в будущем) иметь доступ к растровому изображению просто и легко с помощью имеющихся у них инструментов? Является ли диаграмма полезной/полезной?
Диаграмму ASCII в комментариях кода можно почти всегда легко просмотреть. (Да, могут быть некоторые проблемы, если использовались расширенные символы ASCII или разработчик использует шрифт нефиксированной ширины.)
Вы можете заставить всех в своей команде использовать VS2010 и просто вставлять фактические изображения в исходный файл.
Я согласен с большинством других плакатов: все, что не является кодом (и немного комментариев, но не слишком подробным), должно быть где-то в другом месте, будь то вики или документ.
Я бы предпочел избегать Word из-за различных неудач, которые я испытал в прошлом, но это может быть личное предпочтение. Еще одна вещь: старайтесь иметь хорошие имена для вещей и использовать их в качестве ссылки между вашим кодом и вашими документами. Поэтому, если у вас есть класс (или подпрограмма или модуль), который имеет дело со сценариями, подобными тем, которые вы показали в качестве примера, пожалуйста, назовите его SquareBisector или что-то вроде этого, и его методы будут иметь сценарий A (Point a, Point b), сценарий B (Point a, Line l1) и т.д., а затем записывать документы, объясняющие их в более высокоуровневых терминах, с большим количеством диаграмм, в документе с использованием согласованной терминологии.
Пожалуйста, не вызывайте свои методы "bisectWithTwoPoints (Point firstPoint, Point secondPoint) в коде и" Сценарий A "в документации...
Я собрал список ссылок и небольшой учебник для рисования диаграмм ASCII на Python Wiki. Любые фотографии, которые сэкономит вам некоторое время на чтение текста, безусловно, стоят времени.