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

Материал из Руководство по OpenKore
Перейти к навигации Перейти к поиску

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

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

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

K&R style , with opening brace on the same line with all declarations.

Indent with TABs. Don't use TABs for other means. There is no defined column size for TAB, each developer can have its own preference, respect that.

Стиль 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; # используйте пробелы если вы хотите выровнять код (не отступ) подобный этому
}

Naming

Language: only english

Constants: UPPER_CASE

Variables: $camelCase or $underscore_separated

Packet "names": underscore_separated_words

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

Comments

Language: only english, with no translations to other languages; quotations from sources on another languages may be included if it's necessary

Keywords: FIXME, TODO

Notes

This is a work of fiction. Names, characters, places and incidents either are products of the author's imagination or are used fictitiously. Any resemblance to actual code or data or persons, living or dead, is entirely coincidental.

You should not just go and "fix" names for teleportAuto_search and Glt. Cross, as just renaming them would break existing users' configurations.

Источник — https://ro-fan.ru/wiki/index.php?title=Соглашение_об_оформлении_кода&oldid=2791