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