Стиль написания кода на Wolfram Language16.01.2024 12:00

А затем использовать публичную функцию вот так:

MPAddOne[2] (* => 3 *)

При этом в интерфейсе Mathematica (или в WLJS) при вводе появится вот такая подсказка:

Авто-дополнение и шаблон аргументов

Оформление кода пакета

Ну, а теперь собственно к правилам оформления кода.

• Между выражениями и определениями в пакете необходимо ставить две пустые строки. Как в примерах кода выше. Две пустые строки Mathematica автоматически распознает как границу между ячейками и отображает код пакета в наиболее удобном виде:

  

  Один и тот же код в VS Code и в Mathematica

• В конце каждой строки рекомендуется ставить символ ";", так как в Mathematica пробел может интерпретироваться как умножение. Часто (даже в исходниках Mathematica) я встречаю ошибки с количеством скобок, которые не приводят к падению загрузки пакета, а просто умножают две несвязанные строки.

Имена публичных функций пакета

Все собственные функции пакета из публичного контекста должны быть:

• В PascalCase в виде осмысленных английских слов/фраз/предложений и обозначать действие, т.е. в точности, как встроенные функции

• Но в отличии от встроенных функций, для функций пакетов необходимо указывать префикс, который указывает на имя пакета, в котором определена функция

• Префикс может быть очевидным сокращением или полным названием пакета. Например, в пакете OpenAILink` все функции начинаются с OpenAI*. А функции загруженные из пакета NeuralNetworks` начинаются с префикса Net*.

Следуя этим правилам я назвал функцию из демо-пакета как MPAddOne. А также добавил описание для этой функции в виде сообщения usage. Сообщение составляется по следующему шаблону:

MyFunc::usage = "MyFunc[args] what do MyFunc."; 

То есть в начале строки описания нужно обязательно написать функцию + аргументы, а дальше описание того, что функция делает. В конце ставится точка. Кроме того можно создать описание для каждой перегрузки функции:

MyFunc::usage = 
"MyFunc[x] add 1 to x.
MyFunc[x, y] add y to x."; 

Тогда меню автодополнения будет отображать все перегрузки функции:

Функция с двумя перегрузками

Публичные константы и символы пакета

Часто бывает так, что необходимо создать не только набор функций, но и хранить некоторые данные пакета. Для этих целей используют символы с отложенным вычислением или константы. Все они записываются как системные константы, но внутри пакета. Их так же необходимо объявлять с помощью usage, но без шаблона вызова. Хороший пример такого пакетного символа — это ключ $OpenAIKey из пакета OpenAILink`. Для демо-пакета я создам константу, которая хранит текущую директорию установки. Это распространенная практика и она бывает очень полезна, если вместе с паклетом в систему устанавливается папка с примерами данных, которые пользователю нужно показать:

$MyPackageDirectory::usage = "My package directory.";

Begin["`Private`"]; 

$MyPackageDirectory = DirectoryName[$InputFileName]; 

Т.е. публичные константы пакета:

• Объявляются с usage

• Содержат префикс из $ + имя пакета или сокращение

• Записаны в PascalCase

• Хранят данные связанные с самим пакетом

Приватные имена пакета

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

• camelCase из полных слов английского языка

• Функции обозначают действия

• Префиксы не требуются, так как приватные функции видны только в приватном контексте

• Описание в виде usage не требуется

• Все тоже самое касается приватных переменных пакета и констант

Ниже пример такой функции:

Begin["`Private`"]; 


MyFunc[x_] := myPrivateFunc[x, 1]; 


myPrivateFunc[x_, y_] := x + y; 


End[]; 

Несколько исходных файлов

Если файлов с исходным кодом несколько, то для каждого файла должен быть собственный контекст, где последняя часть совпадает с именем файла. Например структура файлов:

[MyPackage]
- [Documentation]/..
- [Kernel]
- - MyPackage.wl
- - API.wl
- - DB.wl
- PacletInfo.wl

• Обязателен файл MyPackage.wl, который в данном случае стоит называть инициализирующим

• API.wl и DB.wl содержат специфичные связанные функции

• PacletInfo.wl необходимо дополнить, чтобы он новую отражал структуру

Во-первых, как нужно изменить PacletInfo.wl чтобы он поддерживал такую структуру паклета? Необходимо в раздел "Extensions"/"Kernel"/"Context" добавить все файлы и соответствующие им контексты вот так:

"Extensions" -> {
  {
    "Kernel",
    "Root" -> "Kernel",
    "Context" -> 
    {
      {
  	    "KirillBelov`MyPackage`", 
        "MyPackage.wl"
      },
      {
        "KirillBelov`MyPackage`API`",
        "API.wl"
      },
      {
        "KirillBelov`MyPackage`DB`",
        "DB.wl"
      }
    }
  }
}

Тогда при загрузке пакета в сессию WL поймет в каком файле какой контекст и будет правильно их находить. Еще одна важная функция такого объявления файлов и контекстов в том, что инструменты сборки и публикации пакетов используют эту информацию для правильного создания архива.

Поделив исходный код на несколько файлов — мы должны создать специальный инициализирующий файл, имя которого совпадает с именем паклета. Теперь MyPackage.wl должен содержать вот такой код:

BeginPackage["KirillBelov`MyPackage`"]; 


EndPackage[]; 


Get["KirillBelov`MyPackage`API`"]; 


Get["KirillBelov`MyPackage`DB`"]; 

Код выше сначала создает основной контекст без определений, а затем загружает дочерние контексты. Поиск дочерних контекстов (ведь имена файлов напрямую не указаны) происходит при помощи мета-информации в PacletInfo.wl. А вот такой код будет в API.wl:

(* ::Package:: *)

BeginPackage["KirillBelov`MyPackage`API`"];


$MyPackageAPIVersion::usage = "current version of the API."; 


MyPackageGetCurrencyRates::usage = 
"MyPackageGetCurrencyRates[] returns current rates.";


Begin["`Private`"]; 


$MyPackageAPIVersion = "1.0.0"; 


MyPackageGetCurrencyRates[] := {
  <|"ISO" -> "RUB", "Rate" -> 1.0|>, 
  <|"ISO" -> "USD", "Rate" -> 30.0|>
};


End[]; 


EndPackage[]; 

Допустим, дочерний пакет DB.wl должен использовать функции из API.wl. Это необходимо указывать в виде списка используемых контекстов при создании контекста вторым аргументом функции BeginPackage:

(* ::Package:: *)

BeginPackage["KirillBelov`MyPackage`DB`", {
  "KirillBelov`MyPackage`API`"
}];


MyPackageDBSaveCurrency::usage = 
"MyPackageDBSaveCurrency[currency] saves currency to database.
MyPackageDBSaveCurrency[] saves all currencies to database";


Begin["`Private`"]; 


MyPackageDBSaveCurrency[currency_] := With[{db = getDBInstance[]}, 
  AppendTo[db, currency]; 
];


MyPackageDBSaveCurrency[] := 
Map[MyPackageDBSaveCurrency] @ MyPackageGetCurrencyRates[];


End[]; 


EndPackage[]; 

Таким образом мы можем удобно организовать структуру достаточно большого проекта и настроить зависимости между контекстами и функциями пакета. В качестве примера я приведу структуру паклета TelegramBot, состоящую из нескольких файлов:

Кроме определений у меня в файле еще есть самоочевидные комментарии

Скобочки, переносы, пробелы и сокращения

В Wolfram Language есть сразу несколько видов скобочек и огромное количество синтаксического сахара. строгих требований нет, но я опишу тот формат, который на мой взгляд наиболее удобен:

• Скобочки, функции и локализующие конструкции в java-style

• Проблемы слева и справа от операторов:
  {+, -, *, /, ^, &&, ||, >=, <=, ==, ===, >, <}

• Пробелы слева и справа от присваиваний и правил:
  {=, :=, ->, :>, /:, /;, /., /*, ...}

• Пробелы после запятых, двоеточия и точки с запятой

• Отдельно-стоящие списки и ассоциации в C#-style

• Строки кода более 120 символов нежелательны

• Табуляция в 4 проблема. По умолчанию Mathematica использует символ табуляции

• Не злоупотребляйте псевдонимами и сокращениями

Собственно несколько примеров:

myFunc1[x_, y_] := Module[{z = x + y}, 
    z + z ^ 2 - z / 2 * 3
] (*операторы, локализующая функция и присваивание*)


(*правила, замена, условный оператор и условие*)
{1, 2, 5, 4, 2, 0} //. {f___, x_, y_, r___} :> {f, y, x, r} /; y < x


(*список рядом с "=" в java-style и отдельная ассоциация в C#-style*)
users = {
    <|
        "Name" -> "Kirill", 
        "Language" -> "WL"
    |>
}

И отдельно я бы хотел сказать про антипаттерн со злоупотреблением синтаксическим сахаром. Это в первую очередь относится к исходному коду, но прощается в блокнотах, так как весь синтаксический сахар был придуман именно для интерактивного режима. Я имею ввиду использование чудовищных конструкций вроде этой:

Просто кошка пробежалась по клавиатуре

Определения функций

И последний раздел о том, как рекомендуется создавать определения. Эти рекомендации помогут правильно организовать самую важную составляющую любого проекта на WL — собственные функции (а как мы выяснили типичный проект на WL — это набор функций, а затем их вызов):

• Рекомендуется указывать типы параметров или накладывать на них условия

• Не использовать глобальные переменные

• Использовать локальные переменные и Module

• Всегда возвращать результат

• Желательно указывать в комментариях тип результата

• Накладывать условия и печатать сообщения при неправильном вызове

• Не менять состояние окружения, а только преобразовывать данные, если этого не требует бизнес-логика

А теперь я поясню отдельно каждый пункт.

Указание типов. Это делается очень легко и очень помогает быстро понимать что делает функция. Можно сравнить код двух функций ниже и польза будет очевидна:

selectDates[data_] := Select[data, DateObjectQ]; 


selectDates[data_Association] := Select[data, DataObjectQ]; 

В первом случае мы не знаем объект какого типа передается на вход, а во втором мы знаем что это ассоциация, а значит можем понять какие еще функции можно применить специфичные для ассоциаций и что делать с результатом дальше.

Не использовать глобальные переменные. Это очевидно плохо, так как состояние переменные всегда может измениться.

Локальные переменные и Module. Рекомендуется в общем случае использовать именно Module, так как эта функция создает новые уникальные переменные внутри и удаляет их после выполнения блока кода. Пусть имеется определение:

addSqrt[x_] := Module[{sqrt}, 
  sqrt = x ^ 2; 
  x + sqrt
]; 


addSqrt[2] (* => 6 *)

В этом определении используется переменная sqrt. Если даже в текущей сессии будет где-то использоваться глобальная переменная с этим именем, то это никак на нее не повлияет:

sqrt = 4; 


addSqrt[3] (* => 12 *)
sqrt       (* => 4  *)

Но если убрать Module, то произойдет следующее:

sqrt = 4; 


addSqrt[x_] := (
  sqrt = x ^ 2; 
  x + sqrt
); 


addSqrt[3] (* => 12 *)
sqrt       (* => 9  *)

Почему не рекомендуется в общем случае использовать Block? Это функция очень похожа на модуле, но она не создает в момент выполнения новой переменной. Вместо этого она очищает значение локальной переменной. Пока что разница не ясна, но я покажу ее на примере кода. Пусть есть несколько определений, которые зависят друг от друга:

(*выбирает максимальную точку из двух по модулю*)
maxPoint[{p1_List, p2_List}] := If[Total[p1^2] > Total[p2^2], p1, p2]; 


(*получает значение компоненты X максимальной точки*)
getMaxX[{p1_List, p2_List}] := maxPoint[{p1, p2}][[1]]; 

А теперь я создам третьею функцию забыв о том, что вторая вызывает первую. И внутри использую локальную переменную maxPoint:

moveMaxX[{p1_, p2_}] := 
Module[{maxPoint}, 
  getMaxX[{p1, p2}] + 1
]; 


moveMaxX[{{1, 2}, {3, 4}}] (* => 3 + 1 == 4 *)


moveMaxX[{p1_, p2_}] := 
Block[{maxPoint}, 
  getMaxX[{p1, p2}] + 1
]; 


moveMaxX[{{1, 2}, {3, 4}}] (* => {{2, 3}, {4, 5}} *)

Код одинаковый, только локализующая функция разная

Что произошло на скриншоте выше? В первом случае с Module все сработало правильно, а во втором с Block определение maxPoint было очищено на время вызова функции, а значит оно не сработало когда функцию maxPoint пыталась вызвать функция getMaxX. По сути определение maxPoint перестало существовать внутри Block для всех других функций. И в итоге результат получился непредсказуемым. Поэтому функцию Block рекомендуется использовать только если пользователь точно знает, что требуется сделать, а во всех остальных случаях использовать Module.

С With ситуация еще сложнее. По сути в нем создаются не переменные, а константы. Продемонстрировать это можно вот так:

Module[{arr = {1, 2, 3}}, 
  AppendTo[arr, 4]
] (* => {1, 2, 3, 4} *)


With[{arr = {1, 2, 3}}, 
  AppendTo[arr, 4]
] (* => error *)

Во втором случае arr сам по себе является неизменяемым списком, а значит на нем нельзя вызывать функцию AppendTo и вообще работать как с переменной. Нужно просто учитывать, что при использовании With на место arr подставится {1, 2, 3} именно в таком виде.

Возвращение результата. Wolfram Language оперирует неизменяемыми выражениями. А значит в нем не принято (хотя технически можно) вызывать функции, которые ничего не возвращают, но меняют состояние окружения. Все вызовы функций должны принимать на вход аргументы и возвращать преобразованный результат.

Указание типа результат. Это опциональная рекомендация. Я часто этим пользуюсь, чтобы сделать код более читаемым. Вот пример моего кода, где я это активно использовал:

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

Сообщения. Это очень важный пункт, про который многие забывают. Либо его просто игнорируют, так как он не влияет напрямую на функциональность. Но сообщения об ошибках помогают в отладке и рефакторинге кода. При создании определения рекомендуется создать дополнительную перегрузку которая вернет Null и напечатает сообщение с ошибкой и некорректными аргументами. Это делается вот так:

(*само сообщение*)
myFunc::argx = "`1` called with `2` arguments. `3` arguments is expected."; 


(*ошибка аргументов*)
myFunc[args___] := Message[myFunc::argx, myFunc, Length[{args}], 2]; 


(*основное определение*)
myFunc[x_, y_] := x + y; 


(*вызов функции*)
myFunc[1, 2]
myFunc[3]

Сообщение, которое однозначно указывает на функцию, в которой была ошибка

Не менять состояние окружения. Это простое правило связано с тем, что все выражения в WL неизменяемы. Изменить можно только символы и их значения, но не сами выражения. Поэтому именно внутри определений функций не рекомендуется мутировать состояние среды, хотя никто не запрещает мутировать переменные, которые были переданы в функцию в качестве аргумента. В этом случае, если бизнес-логика требует изменения переменных правильнее всего создавать функции специальным образом с использованием удерживания. Допустим есть таблица с пользователями и функция должна добавлять пользователя в нее:

users = {
   <|"Username" -> "Kirill", "Language" -> "WL"|>,
   <|"Username" -> "Eugeny", "Language" -> "C#"|>
};


addUser[table_List, user_Association] := (
   AppendTo[table, user];
   table = DeleteDuplicatesBy[table, #Username &];
   table
);


addUser[users, <|"Username" -> "Ivan", "Language" -> "Russian"|>]

А вот и сообщения о не валидных аргументах

В примере выше ошибка заключается в том, что при вызове функции на место users сразу подставляется неизменяемое выражение, к которому нельзя ничего добавить. Функции AppendTo и Set работают только на символах, но как этого добиться? Нужно не дать вычислиться переменной users! Делается это при помощи добавления атрибута HoldFirst, который удерживает аргумент от вычисления:

users = {
   <|"Username" -> "Kirill", "Language" -> "WL"|>,
   <|"Username" -> "Eugeny", "Language" -> "C#"|>
};


SetAttriutes[addUser, HoldFirst]; 


addUser[table_?ListQ, user_Association] := (
   AppendTo[table, user];
   table = DeleteDuplicatesBy[table, #Username &];
   table
);


addUser[users, <|"Username" -> "Ivan", "Language" -> "Russian"|>]

Теперь users изменился

Таким образом, рекомендуется для всех функций указывать Hold* атрибуты, которые согласно бизнес-логике должны изменять существующие переменные.

Заключение

Соблюдаю ли я сам все эти правила? Конечно же нет. Очень часто я использую то, что позволяет язык, но я не встречал этого ни в одном проекте и репозитории. Я очень сильно страдаю когда смотрю на свой же код, который идет в разрез описанному выше стилю и пытаюсь его исправить — сделать более читабельным. Иногда получается, а иногда нет. Когда я только начинал изучать WL меня просто поразило многообразие и сложность его синтаксиса (а точнее синтаксического сахара). Я старался использовать его везде где только мог в самых невообразимо-сложных формах. Затем, когда я возвращался к своему же коду — то был просто в ужасе! Теперь только Господь знал, что делает мой собственный код. И вот спустя годы использования WL я постарался отбросить все сложности, писать код как можно проще и сохранить свои текущие представления о красивом коде здесь.

Всем спасибо за внимание!

© Habrahabr.ru