Гиперссылка документации по внешнему исходному коду [закрыто]

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

Учитывая обширные возможности, предоставляемые современным средам разработки (мониторы с высоким разрешением, двойные мониторы и т. Д.), Среда IDE может предоставлять полузамкнутые панели, исходный код которых визуально отделен - но внутренне связан с - его соответствующие комментарии. Например, разработчики могут писать комментарии к исходному коду на гиперссылочном языке разметки (ссылаясь на дополнительные требования к программному обеспечению), что одновременно предотвращает загромождение документации исходным кодом.

Какие недостатки могут помешать такому механизму разработки программного обеспечения?

Макет, чтобы помочь прояснить вопрос:

Когда курсор находится на определенной строке в исходном коде (показан синим фоном выше), документация, соответствующая строке на курсоре, выделяется (т. Е. Отличается от других деталей). Как отмечалось в вопросе, документация будет находиться в состоянии блокировки с исходным кодом, когда курсор будет перемещаться по исходному коду. Горячая клавиша может переключаться между «режимом документации» и «режимом разработки».

Потенциальные преимущества включают в себя:

• Больше исходного кода и больше документации на экранах одновременно
• Возможность редактировать документацию независимо от исходного кода (независимо от языка?)
• Пишите документацию и исходный код параллельно без конфликтов слияния
• Документация с гиперссылками в реальном времени с превосходным форматированием текста
• Квазиреальный машинный перевод в реальном времени на разные естественные языки
• Каждая строка кода может быть четко связана с задачей, бизнес-требованием и т. Д.
• Документация может автоматически помечать метку времени при написании каждой строки кода (метрики)
• Динамическое включение архитектурных диаграмм, изображений для объяснения отношений и т. Д.
• Документация из одного источника (например, фрагменты кода тега для включения руководства пользователя).

Замечания:

• Окно документации может быть свернуто
• Рабочий процесс для просмотра или сравнения исходных файлов не будет затронут
• Как происходит реализация - это деталь; документация может быть:
  • хранится в конце исходного файла;
  • разделить на два файла по соглашению ( filename.c, filename.c.doc); или
  • полностью управляемый базой данных
• Под гиперссылочной документацией я подразумеваю ссылки на внешние источники (такие как StackOverflow или Wikipedia) и внутренние документы (т. Е. Вики на поддомене, который может ссылаться на документацию по бизнес-требованиям) и другие исходные файлы (аналогично JavaDocs).

Связанная тема: Что с отвращением к документации в отрасли?

Эта проблема беспокоит меня все время, и я только что понял, в каком направлении мы должны попытаться ее решить (вот как я нашел этот вопрос).

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

Прежде всего, давайте отличать комментарии кода от пользовательской документации.

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

Комментарии пользователей предназначены для людей, пытающихся использовать вашу библиотеку / API, и могут включать примеры использования, объяснение того, почему это было реализовано таким образом, или инструкции о том, как расширить библиотеку. Этот вид комментариев, как правило, очень многословен.

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

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

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

Когда мы чередуем комментарии кода с комментариями пользователей, мы имеем двухстороннюю привязку. Это позволяет нам легко увидеть, какой комментарий соответствует какой части кода. Мы также можем увидеть, если какой-то код недокументирован. То, что он не предлагает, это способ увидеть, обновлен ли комментарий или нет, и это часто случается, когда ваш код трудно читать (потому что документация сделала его уродливым).

Что если вместо двухстороннего связывания у нас есть односторонний? Документация, указывающая на код. Мы могли бы иметь код уценки с помощью специальных команд, таких как:

Some documentation right here that explains the following code:
   @include_file <path/to/some/file>:<line_start>-<line_end>
or
   @include_file <path/to/some/file>
     @starts_with "some regexp or literal text to search"
     @ends_with "another regexp"
or
   @include_file <path/to/some/file>
     @class MyClass
     @method foo
or any combination or way of linking you could imagine

We can even have semantic in the directives:
   @explain_code <path/and/same/of/above>
   @example_code <path/and/same/of/above>
   @performance_notice <path/and/same/of/above>

Which would do basically the same, but it adds the intention of why
do we want to add this code in the first place, which could be 
used different by an IDE. 

Это дает преимущество в виде разметки с некоторыми дополнениями, и с помощью соответствующих инструментов мы могли бы добавить к ней больше пользы.

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

404 Страница не найдена

При работе с кодом вы не хотите, чтобы ваши комментарии терялись, и это происходит, когда вы разделяете код и комментарии в отдельные документы.

Кроме того, поддержание версий между вашим документом комментариев и документом кода вызовет больше боли, чем выгоды.

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

Возможные недостатки, которые я вижу:

• Вам нужен специальный редактор, который реализует эту функцию

• Код больше не просто текст, его легко манипулировать и фиксировать в VCS-es.

• Вам нужно в два раза больше ширины экрана для работы с кодом

Что касается ваших аргументов:

Больше исходного кода и больше документации на экранах одновременно

Но это может быть неудобно, если вы хотите просматривать два файла рядом.

Возможность редактировать документацию независимо от исходного кода (независимо от языка?)

Я бы сказал, что это на самом деле недостаток. Я лично стараюсь держать документацию как можно ближе к коду, чтобы он не устаревал.

Пишите документацию и исходный код параллельно без конфликтов слияния

Опять же, возможно, недостаток. Если ваши документы глубоко чередуются с кодом, как вы можете редактировать их независимо?

Документация с гиперссылками в реальном времени с превосходным форматированием текста

Если он есть в коде, он уже в реальном времени;) Что касается гиперссылок, переход к определению уже реализован в большинстве IDE.

Квазиреальный машинный перевод в реальном времени на разные естественные языки

Я не понимаю, почему вы не можете сделать это с помощью обычных комментариев / строк документации.

Каждая строка кода может быть четко связана с задачей, бизнес-требованием и т. Д.

В этом я не уверен ... Разве это не может быть достигнуто с помощью регулярных комментариев?

Документация может автоматически помечать метку времени при написании каждой строки кода (метрики)

Разве VCS-ы уже не предоставляют такую ​​информацию?

Сказав это, мне очень нравится сам макет - но я не вижу необходимости менять формат файла, его не так сложно сгенерировать из регулярных комментариев. Есть множество генераторов документации, которые делают это, например, Docco и его преемники, такие как Pycco или Marginalia .

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

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

В настоящее время вы можете вставлять гиперссылки в комментарии к коду, а также создавать документы из кода, используя такие инструменты, как Doxygen или Sphinx. Я полагаю, что для лучшей поддержки этих инструментов понадобится какое-то необычное расширение для редактора кода.

Я бы не стал связывать какие-либо строки кода с трекером ошибок или инструментом требований, это лучшая работа для вашего SCM. Затем вы можете увидеть изменения кода в коммите, связанные с задачей. Я бы не стал интегрировать документацию, хранящуюся в коде, с трекером ошибок - вас обидели бы, если вы когда-нибудь захотите перейти на новый (хм, я вижу, что эта функция добавлена ​​в TFS прямо сейчас) или если вы потерял историю коммитов (что происходит)

Помимо того, что @Bogdan уже заявляет, я бы добавил несколько:

• Я настроил свою IDE, чтобы всегда иметь 2 файла одновременно. С функцией, которую вы предлагаете, мне в основном понадобится 2 монитора, чтобы увидеть одинаковое количество информации, и 3, чтобы делать то, что я делаю сейчас с 2.
• Просматривая файл, вы не сразу видите комментарии, и если вы не знаете точно, что ищете, найти его очень сложно.
• При поиске в файле я не могу искать в комментариях напрямую (или так же легко).
• Иногда мне нужно выполнять различные тесты / писать короткие фрагменты кода на живом сервере через ssh . Хотя функциональность, о которой вы говорите, может быть интегрирована с VIM или другими редакторами командной строки - скорее всего, возникнут довольно большие проблемы

• Большинство IDE поддерживают свертывание кода / комментариев , конечными результатами являются следующие:

  Вместо нормального:

  

Сделайте код более читабельным, если вам не нужны комментарии.

Исходный код и документация так, как это должно быть сделано.

http://jasmine.github.io/2.3/introduction.html