Документація щодо вихідного коду з гіперпосиланням [зовнішня]

Чому ми все ще вкладаємо описи вихідного коду на природній мові (тобто, чому було написано рядок коду) у вихідний код, а не як окремий документ?

Враховуючи велику нерухомість, що надається в сучасних середовищах розробки (монітори високої роздільної здатності, подвійні монітори тощо), 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. 

Це має перевагу в тому, що це розмітка з деякими доповненнями, і за допомогою належних інструментів ми могли б додати їй більше значення.

Уявіть, що це один спосіб зв’язування з такими інструментами, як грунт (навіть із завданням на годинник). Ви можете виявити, коли змінюється вихідний файл, подивитися, які файли документації залежать від нього, і попередити користувача (або позначити його десь), чи змінився коментований код.

404 - Сторінка не знайдена

Працюючи з кодом, ви не хочете, щоб ваші коментарі втрачалися, і саме це відбудеться, коли ви розділите код та коментарі до окремих документів.

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

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

Можливі недоліки, які я бачу:

• Вам потрібен спеціальний редактор, який реалізує цю функцію

• Код вже не просто звичайний текст, його легко маніпулювати та виконувати VCS

• Для роботи з кодом вам потрібно вдвічі більше ширини екрана

Щодо ваших аргументів:

Більше вихідного коду та більше документації на екранах (одразу)

Але це може бути незручно, якщо ви хочете переглянути два файли поруч.

Можливість редагування документації незалежно від вихідного коду (незалежно від мови?)

Я б заперечував, що це насправді недолік. Я особисто намагаюся зберегти документацію якомога ближче до коду, щоб вона не застаріла.

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

Знову ж таки, можливо, недолік. Якщо ваші документи глибоко переплетені з кодом, як ви можете їх редагувати самостійно?

Документація в режимі реального часу з гіперпосиланнями з покращеним форматуванням тексту

Якщо він є в коді, це вже в режимі реального часу;) Що стосується гіперпосилань, перехід до визначення вже реалізований у більшості IDE.

Квазичний машинний переклад у реальному часі на різні природні мови

Я не бачу, чому ви не можете цього робити з регулярними коментарями / документами.

Кожен рядок коду може бути чітко пов'язаний із завданням, вимогою бізнесу тощо.

У цьому я не впевнений ... Чи не можна цього досягти регулярними коментарями?

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

Чи вже не надають VCS такі види інформації?

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

По-перше, коментарі doc повинні узгоджуватися з кодом - переміщення їх в інше місце робить лише надзвичайно складними обробку для практично нульового посилення. То навіщо турбуватися!

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

Наразі ви можете вбудовувати гіперпосилання в коментарі до коду, а також можете генерувати документи з коду за допомогою інструментів, таких як Doxygen або Sphinx. Я думаю, що просто знадобиться деякий фантазійний розширення tot він редактор коду для кращої підтримки цих інструментів.

Я б не пов'язував будь-які рядки коду з інструментом відстеження помилок або інструментом вимог, це краща робота для Вашого SCM. Тоді ви можете бачити зміни коду на комісію, які пов'язані із завданням. Я б також не інтегрував документацію, що зберігається в коді, в трекер помилок - ви б накрутили, якщо хотіли б перейти на новий (хм, я бачу, що ця функція додається до TFS зараз) або якщо ви втратили історію фіксації (що трапляється)

Окрім того, що @Bogdan вже заявляє, я додам кілька:

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

• Більшість IDE підтримують згортання коду / коментарів , кінцевими результатами є такі:

  Замість звичайного:

  

Зробіть код більш читабельним, якщо коментарі вам не потрібні.

Вихідний код та документація так, як це слід зробити.

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