SysUtil – это служебные классы и методы, предназначенные для работы со стандартными типами и объектами в Microsoft Dynamics AX 2009. Цель – облегчить разработку и чтение X++ кода.
...мечта написать SysQuery::value(qbds, fieldId, [Enum::One, Enum::Three])
...
...как в чистой Аксапте, так и с установленным axAssist'ом.
Служебные классы позволяют сгруппировать полезные служебные методы в своеобразные namespace'ы.
В Аксапте есть три общепринятых способа размещать служебные методы в классах:
- в классе Global
- в Sys* классах (SysArgs, SysDataArea, SysDictTable, SysCLRType и т.д.)
- в *Util классах (AifUtil, AifWebReferenceUtil и еще несколько, могут содержать не только статические методы)
Также для размещения служебных методов используется всякая разножопица вида: GlobalWeb, Global_<DevLogin>, <PartnerCompanyPrefix>_Tool, Dev_Base и подобные странные названия, понятные только автору.
Ограничения:
- разработчикам может быть запрещено изменять системные классы (включая Global)
- в классе все методы должны иметь уникальные имена (хотя для статического метода и метода инстанса можно было бы разрешить одинаковые имена). В результате у многих Sys-классов мы видим странные имена для одних и тех же действий. Например:
- xSession.getDbSchema - метод инстанса с префиксом get
- Session.aosPort - метод инстанса без префикса get
- Session::getAosPort - статический метод с префиксом get
В данном проекте хотелось бы:
- создать несколько взаимосвязанных служебных методов и классов, которые будут логично сгруппированы
- статические методы разместить в Util-классах
- методы для работы с инстансами разместить в Sys-классах
- классам энумераторов добавлять суффикс Enumerator
Сейчас в проекте определены следующие классы:
- Error
- Any
- Types
- CLR
- Str
- StrUtil
- TextBufferUtil
- TextUtil — текст это "многострочная" строка
- Collection
- Enumerator
- Class
- Record
- Field
- Misc
В целом, используются стандарты, принятые в Аксапте
Отличия от стандарта:
- механизм меток не используется, текст сообщений вставлен "как есть".
xmldoc
не используется из за того, что человеку сложно прочесть код иxmldoc
-комментарий в коде.markdown
-разметка в комментариях допускается. Проект javadoc+markdown+xmlddoc приветствуется.- комментарии и тексты, предназначенные для чтения человеком, пишутся в основном на русском языке. Русскоязычные аксаптоведы, велкам.
- однако, если есть предположение, что текст сообщения может пойти через интернет или через устройства, где возможны ошибки кодировки, то тексты нужно писать символами в кодировке ASCII. Например, класс
error
возвращает текст ошибок на английском.
- однако, если есть предположение, что текст сообщения может пойти через интернет или через устройства, где возможны ошибки кодировки, то тексты нужно писать символами в кодировке ASCII. Например, класс
- в комментариях в публичном проекте допускается
- использовать Javadoc тэги. См. Javadoc Tag Conventions
- писать имена авторов, которые работали над кодом. См.также Javadoc @author tag good practices и Stop using Javadoc @author tag.
- указывать даты и версии (в том числе в тэге
@since
)
- по возможности, оператор
return
возвращает переменную, а не выражение. Возвращаемые переменные могут использоваться при отладке, когда нужно подменить возвращаемое значение. - в версиях ax2009- после блока объявления переменных обязательно нужно вставлять дополнительную
;
, если следующий код начинается не с ключевого слова. Это правило позволяет избежать ошибок, если в Аксапте кто-то уже создал таблицу-класс-тип-enum с таким именем. - да, я знаю о своей привычке
if( operator )
вместо принятогоif (operator)
. Однако, когда мне нужно писать по стандарту, то скорость создания кода у меня падает настолько, что я отказался от переучивания. Извините. Проект с форматером кода приветствуется.
- Названия классов и методов в пререлизах проекта скорее всего будут меняться.
- Код в xpp-файлах конвертирован из xpo только для удобства использования человеком. Оригиналом является код в xpo-проектах, отличия между xpo и xpp всегда трактуются в пользу текста из xpo-проектов.
- Проект опубликован "как есть" под лицензией MIT: вы можете использовать данный код как угодно безо всяких отчислений, автор не дает никаких гарантий и не несет ответственности за возможный эффект от использования кода на проектах.
- проект сознательно сделан для классических версий Аксапты
- в проекте сознательно не используется xmldocs
- README и комментарии сознательно сделаны на русском языке
- тексты записаны простой строкой на русском языке и не используют меток
Проект находится в состоянии альфа версии – названия и состав еще не устаканились. Возможны серьезные изменения.
Буду признателен вашим замечания, предложения и советы по проекту в разделе Issues по поводу:
- имен методов и классов
- code style в проекте
- unit-тестов
- описания методов и документации
Также буду признателен вашим донатам на развитие проекта.
Мазуркин Сергей (mazzy)