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

Багато разів, коли я успадковував чи стикався з науковим кодом, написаним іншими людьми (або зрідка, навіть моєю власною роботою), я помічав, що документація є рідкісною або взагалі не існує. Якщо мені пощастило, я бачу інформативні коментарі. Якщо мені дуже пощастило, є навіть коментарі Doxygen та Doxyfile, так що я маю функціональні інтерфейси та трохи відформатованого HTML для консультацій. Якщо мені дуже пощастило, є додаток до PDF-посібника та приклади, окрім коментарів до Doxygen та вихідних файлів, і я в захваті, тому що це значно покращує моє життя.

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

Я думаю, що документацію на наукове програмне забезпечення можна розділити на три категорії, усі вони необхідні для повного розуміння. Найпростіша і найпоширеніша - індивідуальна документація методу. Для цього існує багато систем. Ви згадуєте Doxygen , Python має pydoc , і в PETSc у нас є власний пакет посів , який генерує наступне .

Однак для будь-якого програмного забезпечення, яке виходить за рамки простої утиліти, вам потрібна інструкція. Це забезпечує високий рівень перегляду мети пакету та того, як його різні функціональні можливості інтегруються для досягнення цієї мети. Це допомагає новій користувачеві структурувати їх код, часто за допомогою використання прикладів. У PETSc ми просто використовуємо LaTeX для посібника, але пакет PyClaw використовує рамку Sphinx, якою я дуже вражений. Одне, що ми реалізували в пакеті посіву, що мені здається дуже корисним, - це зв’язок між прикладом коду та документацією щодо функцій. Наприклад, цей прикладрозв’язує рівняння Брату. Зверніть увагу, як ви можете переходити до посилань для будь-якого користувальницького типу або функціонального виклику та переходити до документації низького рівня та як ці сторінки посилаються на приклади їх використання. Ось як я дізнаюся про нові функції, які сприяють інші люди в проекті.

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

Внутрішньо-кодова документація

Найголовніше - використовувати засоби документації у обраному вами середовищі розробки, так що це означає pydoc для python, javadoc в java або xml коментарі в C #. Це дозволяє легко писати документацію одночасно з написанням коду.

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

Тести як документація

Ще одним важливим аспектом є хороша інтеграція та одиничні тести.

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

Так само одиничні тести часто вказують на зовнішні залежності, явно через які потрібно виправляти макети.

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

Документація вищого рівня

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

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

Мені дуже подобається reStructuredText (rst) , оскільки легко створювати як HTML-сторінки, так і PDF- файли з нього за допомогою сфінкса , і він набагато дружніший, ніж LaTeX , але все ще може включати математичні вирази LaTeX, коли вони вам потрібні.

Я буду заперечувати майже проти кожного пункту, який робить Faheem . Конкретно:

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

2 / "автори повинні розглянути можливість написання документа для публікації, якщо це доречно". На практиці це часто неможливо. Можна писати документи про концепції та алгоритми, але не про інтерфейс та інші дизайнерські рішення. Читачі таких робіт отримають уявлення про те, що це робить; Користувачам програми потрібно знати, які функції викликати, що означає аргументи і т. д. Як користувач, можна більшість часу жити без колишньої і просто розглядати бібліотеку як чорну скриньку, але без неї не обійтися інформація про інтерфейс.

Це гарне запитання. До першого наближення код повинен намагатися самодокументувати. Так, наприклад, якщо програмне забезпечення є командним рядком, ви повинні мати можливість зробити executable --helpабо executable -hнавіть executable( навіть якщо виконуваний файл не робить нічого без аргументів) і мати коротке повернення повідомлення про використання.

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

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

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

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

Якщо ви зацікавлені в грамотному програмуванні, погляньте на org-babel . Він є частиною org-режиму в Emacs і, таким чином, дає вам широкий спектр варіантів експорту (LaTeX, PDF, HTML, ODT) для документації. Emacs може відображати зображення всередині буфера і дозволяти писати математичні рівняння в синтаксисі LaTeX, щоб не потрібно обмежуватися документацією простого тексту.

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

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

У Python є інструменти pep8 та pep257, які повідомлятимуть про відсутніх або неправильних документах. elpy для Emacs також скаржиться на відсутні документи. Numpy конвенції рядок документації з ReStructuredText добре слідувати. Тест з pep8, pep257 та doctest можна налаштувати за допомогою py.test та токсичного запуску автоматично.