Соглашение об оформлении кода
Отказ от ответственности: эта страница сделана из существующего источника 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
, так как простое их переименование нарушит настройки существующих пользователей.