Соглашение об оформлении кода

Отказ от ответственности: эта страница сделана из существующего источника openkore и здравого смысла. Это только рекомендации, которые не всегда применимы.

Обзор

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

Функция или Плагин?

Многие функции (старые и новые) лучше реализованы в виде плагинов. Это помогает в управлении разработкой и использовании. Мы можем связать некоторые "основные" плагины с OpenKore, чтобы они были доступны и включены по умолчанию.

Обратная совместимость

В OpenKore была отличная обратная совместимость как для пользователей, так и для разработчиков, и, как правило, она сохраняется, если не вмешиваются горе-разработчики: давай-ка-всё-сломаем-мне-всё-равно. Это так прекрасно, что почти все команды и параметры конфигурации Skore (предшественника OpenKore с 2003 года), всё ещё могут использоваться точно так же, как и раньше. Это одно из величайших преимуществ Kore - независимо от того, какие функции добавлены, исправлены ошибки, оно всё ещё работает.

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

Недавно реализованные или экспериментальные функции могут меньше зависеть от обратной совместимости.

Обоснованные примеры нарушения совместимости:

• удаление уже устаревших API, которые вызывали проблемы (хэш %field - но даже это могло остаться совместимым, вместо удаления, и это изменение вызвало много независимых проблем)
• переделка сломанных и плохо функционирующих систем (режим XKore очень сильно зависит от системы serverType)
• неопасные изменения имени служебных команд, чтобы получить более единообразное наименование команд в целом (cl теперь список чата (chat list), а не очистка журнала (clear log))

Необоснованные примеры нарушения совместимости:

• настраиваемые для каждого сервера названия предметов/умений/монстров, которые ломают все конфигурации - нарушают совместимость
• изменения аргументов хука без необходимости (r7726) - изменение существующих аргументов хука - плохая идея, просто добавьте новые аргументы или добавьте больше хуков (добавление аргументов к существующим хукам - это нормально); в любом случае все несовместимые изменения хуков ДОЛЖНЫ быть добавлены в документацию Porting Plugins
• нарушение существующего поведения команд (r7653 - исправлено)
• неясные и не должным образом протестированные (необходимы юнит-тесты) изменения основных систем, которые могут привести к поломке многих случайных вещей (экземпляры карт - исправлено; LOS (прямая видимость))

Примеры совместимости:

• storageAuto_npc_type сообщит вам, пытаетесь ли вы использовать устаревшее (и удаленное) значение '0'

Изменения в поведении

Хотя некоторые изменения не нарушают совместимость, они могут вносить нежелательные изменения в поведении. Относитесь к этой ситуации так же, как к изменениям совместимости.

Неоправданные примеры нарушения поведения:

• удаление безопасного поведения по умолчанию, на которое полагаются многие пользователи. Сделать параметром не по умолчанию, хотя поведение не изменились. (r8118, shopAuto_open и lockMap - исправлено)

Согласованность

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

Плохие примеры:

• противоречие в наименовании одной и той же вещи в разных функциях (unknown_09A1 / sync_received_characters / sync_received_characters_09A1, receive_characters_info / characters_slots_info для одних и тех же пакетов в разных serverTypes) и последующие "исправления" XKore, которые сломали все serverTypes, за исключением того, который был исправлен; пакет skill_post_delay был добавлен в serverType0, оставив существующий skill_postdelay в kRO без изменения); для пакетов и прочего с известными идентификаторами всегда выполняйте поиск по всему коду, чтобы выяснить, как он уже вызывался, и сделайте для него одно общее имя

• полное несоответствие между именем и функцией (teleportAuto_search используется не для телепортации и не будет выполнять какой-либо автоматический поиск; пакет buy_bulk_vender предназначен не для покупки, а для продажи предметов)

• заимствование существующих названий команд (pl, ml, vl и т. д. - это "списочные" команды, но cl команда очистки журнала (clear log) - исправлено)

• несоответствие в области именования (shop_LockOnly влияет только на параметры shopAuto_*, сравните с shop_random, которое влияет как на автоматические, так и на открытые вручную магазины - исправлено)

• несоответствие регистра символов в названии переменных (shop_LockOnly], в то время как все другие опции используют строчные буквы после подчеркивания; пакеты GANSI_RANK и ISVR_DISCONNECT, тогда как все другие пакеты используют строчные имена - исправлено)

• несоответствие узнаваемости имени в разных функциях (shop_LockOnly, хотя уже были inLockOnly, attackAuto_inLockOnly, avoList_inLockOnly - исправлено)

• использование случайных сокращений, особенно в списке, где ни один другой элемент не использует сокращенным (Glt. Cross имя профессии), особенно когда он используется в настройках (такие имена обычно не угадываемые, если Вы не просматриваете исходники); наши собственные условные обозначения, такие как LOS, KS, Dmg, лучше придерживаться. Если Ваше имя не вписывается в отображение какого-либо интерфейса, это проблема только интерфейса и её следует решать именно в интерфейсе (есть несколько решений) - имена не должны искажаться из-за какого-либо интерфейса

Если Вы не знаете, как назвать свои новые опции или что-то ещё, просто спросите на форуме или в чате

форматирование

Стиль K&R (Kernighan & Ritchie), скобка остаётся на той же строке, где располагается часть кода, к которой она (скобка) принадлежит. В качестве отступов используются TABs. Не используйте TABs для других целей. Для TAB не определен размер столбца, каждый разработчик может иметь свои предпочтения, уважайте это.

sub test {
<TAB> if ($a == $b) {
<TAB> <TAB> something();
<TAB> <TAB> something_else($a, $b);
<TAB> }
<TAB> $twenty = 20;
<TAB> $ten    = 10; # используйте пробелы если вы хотите выровнять код (не отступ) подобный этому
}

Наименование

Язык: только английский

Константы: ВЕРХНИЙ_РЕГИСТР

Переменные: $camelCase или $underscore_separated

Пакет "names": подчёркивание_между_словами

Config option names: camelCase, regular words like "auto" at the end, however underscore may separate a common prefix (teleportAuto). Underscore is also internally used to represent config blocks Имена параметров конфига: горбатыйРегистр (camelCase), обычные слова, такие как "auto" в конце, подчеркивание может отделять общий префикс (teleportAuto). Подчеркивание также используется в блоках конфига

Комментарии

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

Ключевые слова: FIXME (исправить), TODO (доделать в будущем)

Замечания

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

Вы не должны сейчас просто идти и «исправлять» имена для teleportAuto_search и Glt. Cross, так как простое их переименование нарушит настройки существующих пользователей.