Документація, що принижує гідність - як з цим боротися?

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

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

• мотивації дизайнерських рішень для частин API (наприклад, ми зробили цю потворну річ, тому що саме ця стороння бібліотека хоче, щоб це було зроблено таким чином, тому що ця інша бібліотека ..., тому що ...)
• пояснення того, як ми маємо справу з певними загальними завданнями (наприклад, показ тривіального спливаючого вікна, який повинен посилатися на відповідні стилі додатків, зареєструватися в компоненті реєстру та реалізувати деякий інтерфейс для автоматичного "сканування" іншим компонентом)
• передовий досвід (як суб'єктивний, ми насправді записуємо цей матеріал)
• конфігурація середовища, необхідні інструменти та його налаштування

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

Проблема

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

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

Звичайна деградація. Код змінено, вікі залишається тим самим. Наступного разу, коли хтось шукає інформацію, те, що він зазвичай знаходить, - це застарілий, низькоякісний матеріал - і цікавиться, що відбувається, чи точні речі, які він знайшов, або (що ще гірше), які його частини. І те, що мало допомогти, зрештою робиться навпаки.

На даний момент, здається, люди знають про проблему, включається керівництво проекту, але, мабуть, ніхто не турбується робити щось з цим (або має ще цікаві речі).

Моя первісна думка полягала в тому, щоб кинути це все у небуття (після того, як мене кілька разів поспіль укусили застарілі "підказки"), але я вважаю, що це може бути занадто екстремально. Деяку інформацію варто зауважити та її добре прочитати іноді, але проблема все одно: як ви маєте справу з її "сучасністю" ? Чи пов’язано це якось із вихідним кодом (тому коли перевіряється оновлена ​​версія файлу, автор статті отримує повідомлення про те, що йому може знадобитися переглянути код / ​​статтю)? Призначили людину "щодня" спостерігати за нею? Чи регулярно проводите чистки?

Здається, ви запевняєте занадто багато дрібниць у вікі.

Документи блоки коду та методи в коді . Постарайтеся зробити свій код самодокументуванням, щоб не потрібно робити багато коментарів. Питання одиничних тестів також може допомогти.

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

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

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

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

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

Не рідкість бачити, як люди "очікують" отримання програмної документації, коли її немає.

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

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

Якщо щось швидко змінюється, це не повинно підтримуватися поза кодом.

мотивації дизайнерських рішень для частин API

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

Звичайна деградація. Код змінено, вікі залишається тим самим.

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

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

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

Якщо ви використовуєте мову .net, подивіться на ( Sandcastle ), який приймає документацію XML (/// у C #) та перетворює її у формат довідки MSDN.

Формат включає опис, коментарі та має можливість включати зразки коду, а також деякі інші функції. Ви можете виводити у формати .CHM, .HsX, .MSCH та HTML / ASP.NET. Фактичний проект додається до вашого рішення та будується на сервері збірки. Ми зробили це і розмістили на веб-сайті кожен випуск, і споживачі люблять це, оскільки документація стосується випуску та постійно оновлюється.

Ви також можете вказати, що потрібно включити в документацію. В даний час у нас є 2 проекти: один для зовнішніх споживачів, який включає лише контракти та відповідні товари (класи, перерахунки тощо), і один для внутрішніх розробників, який включає все в API, включаючи приватні та внутрішні позиції.

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

Я б зосередив увагу на двох областях, 1) Код. 2) Примітки та документ без коду.

1) Код.

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

Замість цього типу псевдокоду:

# Routine by mdd on 7/25/2012
# processes cars for sale
a=0
col = Car.all
Collection.loop |a|
 if a.stat = 'fs' then 
   a+= a.value    
   call easo 
  endif
end

Зробіть код, який виглядає приблизно так:

accumulating_potential_sale_revenue = 0
cars_to_check = Car.all
cars_to_check.loop |one_car|
  if one_car.sell_status == 'for_sale'
    accumulating_potential_sale_revenue+= one_car.sale_price
    call email_about_special_offer(car)
  endif
end

Використовуйте керування джерелами, щоб відстежувати інформацію "хто робив коли".

2) Некод

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