Настоящие причины, по которым пакеты Julia недостаточно документированы.
Вступление
Хотя излюбленным языком большинства специалистов по анализу данных, вероятно, является Python или, что менее вероятно, R, мой любимый язык программирования - точка - это Julia. Язык Julia - довольно молодой, JIT-скомпилированный язык программирования, в основе которого лежит концепция множественной диспетчеризации общей концепции программирования. Они не только используют это универсальное средство, но и применяют его повсюду на языке, с просто потрясающими результатами. Если вы хотите прочитать всю статью, которую я написал о Джулии и гениальном использовании множественной отправки на этом языке, вы можете просмотреть эту здесь:
Пару дней назад я написал статью о проблемах, с которыми, как мне кажется, сталкивается Джулия как язык программирования. Первая и самая важная из этих проблем, как некоторые могли ожидать, заключается в том, что Джулии нужна лучшая экосистема для работы. Последней было то, что разработчики языка не совсем четко обозначили нишу языка в отрасли, в то время как они явно указано, где язык не предназначен для заголовка. Однако есть ли за этим более неявный смысл - я действительно не могу сказать, так как я не являюсь членом их команды. В любом случае, именно на этих двух проблемах я хотел сосредоточить целую статью:
Документация.
Кроме того, если вам интересна эта статья, вы можете прочитать ее отдельно здесь:
Способствующие факторы
В вышеупомянутой статье я обсуждал, как, на мой взгляд, проблема с документацией Джулии коренится в Documenter.jl. Разработчики программного обеспечения ленивы, и это еще более верно, когда речь идет о документации по разработке программного обеспечения. Прохождение всей миссии по разработке пакета может быть невероятно напряженным. После того, как пакет разработан, его энергичное тестирование, создание некоторых файлов, выбор лицензии - и, наконец, - выпуск… Но потом вы понимаете, что вам все еще нужно беспокоиться о документации.
К счастью, Documenter.jl можно использовать для автоматизации этого процесса. Кроме того, документация для пакетов автоматически создается на веб-сайте Julia Hub. Излишне говорить, что это очень крутой подход, но неужели это слишком просто? Давайте также помнить, что все, что вам нужно сделать для документирования программного обеспечения с помощью Julia, - это просто вызвать макрос autodoc. При этом, хотя многие основные пакеты вместо этого предпочитают писать полное описание внутри файлов Documenter, что хорошо.
При этом я думаю, что это также делает документацию настолько простой, что ее легко не заметить. Излишне говорить, что это может быть проблематично, когда единственное, с чем можно работать, - это строки документации, которые редко могут содержать примеры или сложные описания типов. Излишне говорить, что, безусловно, оптимально иметь хорошо написанную документацию вместо простых автоматически сгенерированных строк документа в документе HTML. Эти существа сказали, что последнее слишком легко сделать, что, как мне кажется, повредило документацию.
Еще одна вещь, которая испортила документацию Julia, - это то, что многие пользователи даже не знают, как документировать свое программное обеспечение. Почему это? Потому что хотите верьте, хотите нет,
Documenter.jl, а документирование Юлии в целом ПЛОХО ДОКУМЕНТИРУЕТСЯ.
Для меня это забавная ирония. Только представьте;
«Я не могу задокументировать свой пакет, потому что пакет, который мне нужно использовать для документирования моего пакета, имеет плохую документацию». Это даже не то, однако, просто не так много исчерпывающих описаний Джулии, которые объясняют, как все это делать - что, безусловно, может расстраивать! Некоторые программисты Юлии даже не знают, что Documenter.jl существует!
Самая большая причина
Самая главная причина, по которой программное обеспечение Julia очень часто недокументировано или очень плохо документировано, даже не приходила мне в голову, когда я писал свою предыдущую статью. Только после этого я получил ответ от другого программиста и фаната Джулии, в котором говорилось о том, что они также столкнулись с множеством проблем с документацией. На самом деле, они написали, что я был для них самым большим источником информации о Джулии - что было моей целью при написании статей о Джулии - постоянно учить языку. При этом я чувствовал себя успешным, но также размышлял, почему языки, в которых даже нет таких инструментов, как Documenter.jl, часто имеют лучшую документацию. Я даже провел небольшое исследование, изучая другие пакеты для таких языков, как C, Ruby, JavaScript, F #, Vala и другие.
Проведя все это исследование, я пришел к выводу, что есть очень веская причина, по которой Юлию редко документируют, а вместе с тем - очень трудно задокументировать. Причина кроется в самом языке программирования, в самой парадигме программирования:
Множественная отправка.
Подождите, значит, проблема в многократной отправке !? Хотя ни одна из проблем, обсуждаемых в этой статье, не является окончательной проблемой, легко понять, почему множественная отправка может иметь значительное влияние на способность разработчика документировать свой код Julia.
Почему множественная отправка?
Чтобы понять, почему множественная отправка является проблемой для документации, давайте сначала рассмотрим пример множественной отправки в Julia. Рассмотрим следующие два типа:
tru = "true" fls = 0
Здесь у нас есть fls, false, целое число, представляющее логическое значение. Выше было объявлено, что у нас есть true, true, еще одно логическое значение, но оно содержится в строке. И с тем, и с другим нужно обращаться по-разному. Мы можем обработать целое число, просто преобразовав тип bool в целое число 0. Однако, если мы попытаемся сделать это с нашей строкой, мы получим ошибку метода. Прежде чем мы перейдем к строке, давайте напишем функцию для этого целого числа:
turn_bool(x::Int64) = Bool(x)
Хотя это довольно простой пример, давайте теперь займемся строкой. Строку необходимо проанализировать на соответствующий тип данных, bool, с помощью метода parse ():
turn_bool(x::String) = parse(Bool, x)
Теперь давайте рассмотрим написание строки документации для этих функций.
"""Turns an integer between 0:1 to a boolean type.""" turn_bool(x::Int64) = Bool(x) """Turns a string, true, false, or 1, 0, into a boolean type.""" turn_bool(x::String) = parse(Bool, x)
Всякий раз, когда мы вызываем эту функцию с использованием синтаксиса? (), Мы получим оба из них последовательно, как и следовало ожидать, что идеально!
?(turn_bool)
Однако проблема здесь возникает, когда либо только одна версия функции оформлена в виде строки документа, ИЛИ - чаще всего строки документа не предоставляют входные аргументы. Это проблематично, потому что из-за этого невозможно определить, какие функции будут делать с конкретными типами. Например, если вы посмотрите на индексирование фреймов данных DataFrames.jl, вы в конечном итоге встретите пример с методом filter () - именно так это и должно быть сделано. Что ж, если вы вызовете метод filter () с помощью? (), Вы увидите, что каждое использование этой функции в Base и DataFrames.jl полностью недокументировано !!! Таким образом демонстрируются фундаментальные недостатки этих базовых функций, используемых во всем языке - пользователи не чувствуют необходимости документировать их использование!
Заключение
Я действительно счастлив немного поговорить о документации по программному обеспечению Julian. Лично я должен признать, что тоже не лучшим образом документировал свое программное обеспечение. Тем не менее, скоро выйдут два больших стабильных выпуска для моих ведущих пакетов, Lathe и OddFrames, и оба они будут очень хорошо документированы и просты для понимания, я могу это гарантировать! Большое спасибо за чтение. Я думаю, что эти проблемы очень легко исправить, сообществу просто нужно определиться с этой проблемой и попытаться улучшить ее в целом. Надеюсь, мы, как Julians, сможем собраться вместе и предоставить языку пакеты и соответствующую документацию, которых он заслуживает. Прекрасно отдохните здесь, на Medium!
