Почему мы до сих пор встраиваем описания исходного кода на естественном языке (т.е. причину, по которой была написана строка кода) в исходный код, а не как отдельный документ?
Учитывая обширные возможности, предоставляемые современным средам разработки (мониторы с высоким разрешением, двойные мониторы и т. Д.), Среда IDE может предоставлять полузамкнутые панели, исходный код которых визуально отделен - но внутренне связан с - его соответствующие комментарии. Например, разработчики могут писать комментарии к исходному коду на гиперссылочном языке разметки (ссылаясь на дополнительные требования к программному обеспечению), что одновременно предотвращает загромождение документации исходным кодом.
Какие недостатки могут помешать такому механизму разработки программного обеспечения?
Макет, чтобы помочь прояснить вопрос:
Когда курсор находится на определенной строке в исходном коде (показан синим фоном выше), документация, соответствующая строке на курсоре, выделяется (т. Е. Отличается от других деталей). Как отмечалось в вопросе, документация будет находиться в состоянии блокировки с исходным кодом, когда курсор будет перемещаться по исходному коду. Горячая клавиша может переключаться между «режимом документации» и «режимом разработки».
Потенциальные преимущества включают в себя:
- Больше исходного кода и больше документации на экранах одновременно
- Возможность редактировать документацию независимо от исходного кода (независимо от языка?)
- Пишите документацию и исходный код параллельно без конфликтов слияния
- Документация с гиперссылками в реальном времени с превосходным форматированием текста
- Квазиреальный машинный перевод в реальном времени на разные естественные языки
- Каждая строка кода может быть четко связана с задачей, бизнес-требованием и т. Д.
- Документация может автоматически помечать метку времени при написании каждой строки кода (метрики)
- Динамическое включение архитектурных диаграмм, изображений для объяснения отношений и т. Д.
- Документация из одного источника (например, фрагменты кода тега для включения руководства пользователя).
Замечания:
- Окно документации может быть свернуто
- Рабочий процесс для просмотра или сравнения исходных файлов не будет затронут
- Как происходит реализация - это деталь; документация может быть:
- хранится в конце исходного файла;
- разделить на два файла по соглашению (
filename.c
,filename.c.doc
); или - полностью управляемый базой данных
- Под гиперссылочной документацией я подразумеваю ссылки на внешние источники (такие как StackOverflow или Wikipedia) и внутренние документы (т. Е. Вики на поддомене, который может ссылаться на документацию по бизнес-требованиям) и другие исходные файлы (аналогично JavaDocs).
Связанная тема: Что с отвращением к документации в отрасли?
источник
Gson()
объект быть инстанцирован по отношению к классу MainActivity, ни то, как он относится к решению конкретных требований бизнеса. Описание самого кода, а не API, которые он использует, может быть в отдельном окне, независимо от сторонних JavaDocs.Ответы:
Эта проблема беспокоит меня все время, и я только что понял, в каком направлении мы должны попытаться ее решить (вот как я нашел этот вопрос).
Я думаю, что проблема со связанной документацией была ошибочной, когда мы решили включить пользовательскую документацию в исходный код. Как и Докко.
Прежде всего, давайте отличать комментарии кода от пользовательской документации.
Комментарии к коду, как правило, в лучшем случае, когда они короткие, на самом деле очень короткие, так что я могу на самом деле прочитать код, который выполняет эту работу, не видя поэзии о том, почему и как она работает.
Комментарии пользователей предназначены для людей, пытающихся использовать вашу библиотеку / API, и могут включать примеры использования, объяснение того, почему это было реализовано таким образом, или инструкции о том, как расширить библиотеку. Этот вид комментариев, как правило, очень многословен.
Я согласен с тем фактом, что документация должна быть написана в виде простого текста, поэтому она не исправлена поставщиком, и ее легко добавить в VCS. Но я думаю, что хранение пользовательской документации в исходном файле было большой ошибкой по крайней мере по двум причинам:
Итак, почему мы хотим, чтобы это было в одном файле? Ну, никто не хочет, чтобы их документы были синхронизированы из кода. Но мы делаем это в любом случае, и особенно сейчас, с большим успехом Markdown. Который, я думаю, находится на правильном пути, но если не дотягивает, недооценивают.
Когда мы чередуем комментарии кода с комментариями пользователей, мы имеем двухстороннюю привязку. Это позволяет нам легко увидеть, какой комментарий соответствует какой части кода. Мы также можем увидеть, если какой-то код недокументирован. То, что он не предлагает, это способ увидеть, обновлен ли комментарий или нет, и это часто случается, когда ваш код трудно читать (потому что документация сделала его уродливым).
Что если вместо двухстороннего связывания у нас есть односторонний? Документация, указывающая на код. Мы могли бы иметь код уценки с помощью специальных команд, таких как:
Это дает преимущество в виде разметки с некоторыми дополнениями, и с помощью соответствующих инструментов мы могли бы добавить к ней больше пользы.
Представьте себе это одностороннее связывание с такими инструментами, как grunt (даже с задачей наблюдения). Вы можете определить, когда исходный файл изменяется, посмотреть, какие файлы документации зависят от него, и предупредить пользователя (или выделить его где-нибудь), если закомментированный код изменился.
источник
404 Страница не найдена
При работе с кодом вы не хотите, чтобы ваши комментарии терялись, и это происходит, когда вы разделяете код и комментарии в отдельные документы.
Кроме того, поддержание версий между вашим документом комментариев и документом кода вызовет больше боли, чем выгоды.
Некоторые из предложений, которые вы делаете, мне действительно нравятся, но могут быть легко реализованы при наличии кода и комментариев в 1 файле.
источник
Возможные недостатки, которые я вижу:
Вам нужен специальный редактор, который реализует эту функцию
Код больше не просто текст, его легко манипулировать и фиксировать в VCS-es.
Вам нужно в два раза больше ширины экрана для работы с кодом
Что касается ваших аргументов:
Но это может быть неудобно, если вы хотите просматривать два файла рядом.
Я бы сказал, что это на самом деле недостаток. Я лично стараюсь держать документацию как можно ближе к коду, чтобы он не устаревал.
Опять же, возможно, недостаток. Если ваши документы глубоко чередуются с кодом, как вы можете редактировать их независимо?
Если он есть в коде, он уже в реальном времени;) Что касается гиперссылок, переход к определению уже реализован в большинстве IDE.
Я не понимаю, почему вы не можете сделать это с помощью обычных комментариев / строк документации.
В этом я не уверен ... Разве это не может быть достигнуто с помощью регулярных комментариев?
Разве VCS-ы уже не предоставляют такую информацию?
Сказав это, мне очень нравится сам макет - но я не вижу необходимости менять формат файла, его не так сложно сгенерировать из регулярных комментариев. Есть множество генераторов документации, которые делают это, например, Docco и его преемники, такие как Pycco или Marginalia .
источник
Во-первых, комментарии к документу должны идти вместе с кодом - перемещение их в другое место только делает вещи невероятно трудными для обработки практически с нулевым коэффициентом усиления. Так зачем?
Однако, что можно сделать, это взять эти встроенные комментарии и спрятать их в редакторе, показав их в виде всплывающей подсказки или всплывающей подсказки или еще чего-нибудь по необходимости. Я надеюсь, что такой подход может побудить людей писать гораздо больше документации для кода - например, описание класса может идти вместе с классом, а не во внешнем проектном документе.
В настоящее время вы можете вставлять гиперссылки в комментарии к коду, а также создавать документы из кода, используя такие инструменты, как Doxygen или Sphinx. Я полагаю, что для лучшей поддержки этих инструментов понадобится какое-то необычное расширение для редактора кода.
Я бы не стал связывать какие-либо строки кода с трекером ошибок или инструментом требований, это лучшая работа для вашего SCM. Затем вы можете увидеть изменения кода в коммите, связанные с задачей. Я бы не стал интегрировать документацию, хранящуюся в коде, с трекером ошибок - вас обидели бы, если вы когда-нибудь захотите перейти на новый (хм, я вижу, что эта функция добавлена в TFS прямо сейчас) или если вы потерял историю коммитов (что происходит)
источник
Помимо того, что @Bogdan уже заявляет, я бы добавил несколько:
Большинство IDE поддерживают свертывание кода / комментариев , конечными результатами являются следующие:
Вместо нормального:
Сделайте код более читабельным, если вам не нужны комментарии.
источник
Исходный код и документация так, как это должно быть сделано.
http://jasmine.github.io/2.3/introduction.html
источник