Функциональная документация программирования [закрыто

Question

Есть ли какая -либо стандартная документация (например, UML для OO) для функциональных языков? После загрузки дивана DB, который написан в Erlang, и просмотра исходного кода, который я был шокирован, вряд ли есть линия документации. Не нужно ли документировать, как все эти функции зависят друг от друга? Есть ли лучшие документированные проекты среднего размера свободно доступны, как обстоят дела, используя эту парадигму?

Answer 1

Код должен быть задокументирован, независимо от языка.

Кажется Стандартный стиль документации под названием EDOC. Анкет EDOC может создать внешнюю документацию API; Цитата из одного источника:

EDOC является стандартным приложением Erlang для документирования API Erlang непосредственно внутри кода Erlang.

Это ссылается в Раздел документации на erlang.org:

EDOC позволяет написать документацию программы Erlang в качестве комментариев в самом исходном коде, используя теги в форме «@name ...». Исходный файл не должен содержать теги для EDOC, чтобы сгенерировать его документацию, но без тегов результат будет содержать только основную доступную информацию, которая может быть извлечена из модуля.

А Основной поиск Google Приведет вас отсюда.

Answer 2

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

Erlang был разработан в Ericsson, а телекоммуникационная индустрия имеет очень сильную культуру и записи тестирования. Меня не удивит, если документация о том, как должны работать эти функции, находится где -то в испытательном наборе.

Резюме: Двумя самыми близкими вещами в стандарте являются типы (для функциональных языков со статическими системами) и контрактами (для функциональных языков, которые не имеют статических систем).

Answer 3

Это очень интересная проблема!

Есть две проблемы - первая комментирует код и написал некоторую документацию (в текстовой форме). Это должно быть сделано обычным способом, как на языках OO. Вы просто напишите обзор всех модулей, функций и типов, которые вы используете в своем проекте. В F# (функциональный язык для .NET) вы можете написать XML -комментарии довольно похожими, как в F#, и генерировать документацию из этих комментариев. Я верю F# документация на MSDN генерируется автоматически из этих комментариев. Вот пример из исходного кода F# (если вы установите F# для VS 2008, он также установит исходный код основных библиотек, что может быть интересным ресурсом):

/// Return the first element of the list.
///
/// Raises <c>System.ArgumentException</c> if <c>list</c> is empty
val head: list:'T list -> 'T

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

let custNames = customers |> List.map (fun customer -> customer.Name) 
let empNames = employees |> List.map (fun employee -> employee.Name) 
let result = List.concat [custNames; empNames]

Это может быть хорошо визуально представлено путем рисования потока данных:

+-----------+    +-----+
| customers |--->| map |\
+-----------+    +-----+ \ +--------+   +--------+
                          >| concat |-->| result |
+-----------+    +-----+ / +--------+   +--------+
| employees |--->| map |/
+-----------+    +-----+

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