Соглашение об оформлении кода: различия между версиями

Материал из Руководство по OpenKore
Перейти к навигации Перейти к поиску
← Предыдущая правка
м 4epT переименовал страницу Development Conventions в Соглашения по разработке
Нет описания правки
 
(не показано 6 промежуточных версий этого же участника)
Строка 1: Строка 1:
Disclaimer: this page is made of existing openkore source and common sense. These are only guidelines which may not always apply.
Отказ от ответственности: эта страница сделана из существующего источника openkore и здравого смысла. Это только рекомендации, которые не всегда применимы.


== Overview ==
== Обзор ==


''Ultimately, the goal is to write code that fits in with the other code around it and the system as a whole. If the file you are editing already deviates from these guidelines, do what it does. After you edit a file, a reader should not be able to tell just from coding style which parts you worked on.'' - from Plan 9 coding conventions for C
''Основная цель состоит в том, чтобы написать код, который бы соответствовал другому коду вокруг него и системе в целом. Если файл, который Вы редактируете, уже отклоняется от этих рекомендаций, делайте также. После того, как Вы отредактируете файл, читатель не должен определить над какими частями вы работали по стилю кодирования. '' - из Соглашения об оформлении кода для C (пункт 9)


== Feature or Plugin? ==
== Функция или Плагин? ==


Many features, old and new, are better implemented as plugins. It helps with managing development and usage. We can bundle some "core" plugins with openkore so they would be available and enabled by default.
Многие функции (старые и новые) лучше реализованы в виде плагинов. Это помогает в управлении разработкой и использовании. Мы можем связать некоторые "основные" плагины с OpenKore, чтобы они были доступны и включены по умолчанию.


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


OpenKore used to have excellent backwards compatibility both for users and developers, and generally still does, unless non-caring let-s-break-this-I-dont-care contributors prevail. It's so excellent that almost all [http://ro.horoy.com/help_main.html commands and configuration options of Skore], the predecessor of OpenKore back from 2003, still may be used exactly in the same way as before. That's one of the greatest advantages of Kore - regardless of features added, bugs fixed and systems reworked, you're still good with it as you were some day.
В OpenKore была отличная обратная совместимость как для пользователей, так и для разработчиков, и, как правило, она сохраняется, если не вмешиваются горе-разработчики: давай-ка-всё-сломаем-мне-всё-равно. Это так прекрасно, что почти все [http://ro.horoy.com/help_main.html команды и параметры конфигурации Skore] (предшественника OpenKore с 2003 года), всё ещё могут использоваться точно так же, как и раньше. Это одно из величайших преимуществ Kore - независимо от того, какие функции добавлены, исправлены ошибки, оно всё ещё работает.


New versions of openkore shouldn't break old configurations and plugins. It means to avoid unwarranted changes to any existing behaviour, any default behaviour or any internal programming interfaces and names. It doesn't help users only, but developers familiar with various parts of codebase as well.
Новые версии OpenKore не должны ломать старые конфигурации и плагины. Это означает, что следует избегать необоснованных изменений любого существующего поведения, любого поведения по умолчанию или любых внутренних интерфейсов и имён. Это помогает не только пользователям, но и разработчикам, знакомым с различными частями кодовой базы.


Recently implemented or highly experimental stuff may depend less or backwards compatibility.
Недавно реализованные или экспериментальные функции могут меньше зависеть от обратной совместимости.


Justified compatibility breaking examples:
Обоснованные примеры нарушения совместимости:
* removal of already deprecated APIs which caused problems (%field hash - but even it could have been tie'd instead of removal, and this change caused many problems regardless)
* удаление уже устаревших API, которые вызывали проблемы (хэш %field - но даже это могло остаться совместимым, вместо удаления, и это изменение вызвало много независимых проблем)
* rework of broken and hardly functioning systems (XKore transition to be more dependent on serverType system)
* переделка сломанных и плохо функционирующих систем (режим XKore очень сильно зависит от системы serverType)
* non-dangerous name changes of utility commands, to get more uniform command naming overall ([[cl]] is chat list now, not clear log)
* неопасные изменения имени служебных команд, чтобы получить более единообразное наименование команд в целом ([[cl]] теперь список чата (chat list), а не очистка журнала (clear log))


Unjustified compatibility breaking examples:
Необоснованные примеры нарушения совместимости:
* customizable per-server item/skill/monster names, which broke all configurations - broke compatibility and interoperability hard
* настраиваемые для каждого сервера названия предметов/умений/монстров, которые ломают все конфигурации - нарушают совместимость
* hook argument changes just for the sake of it ([http://openkore.svn.sourceforge.net/viewvc/openkore?view=revision&revision=7726 r7726]) - changing existing hook arguments is never a good idea, just add more arguments or add more hooks instead (adding arguments to existing hooks is fine); anyway, all incompatible hook changes MUST be added to [[Porting Plugins]] documentation
* изменения аргументов хука без необходимости ([https://github.com/OpenKore/openkore/commit/a56ce36c0479746807104a08e30cd9778755ec01 r7726]) - изменение существующих аргументов хука - плохая идея, просто добавьте новые аргументы или добавьте больше хуков (добавление аргументов к существующим хукам - это нормально); в любом случае все несовместимые изменения хуков ДОЛЖНЫ быть добавлены в документацию [[Porting Plugins]]
* breaking existing behaviour of commands ([http://openkore.svn.sourceforge.net/viewvc/openkore/openkore/trunk/src/Commands.pm?r1=7653&r2=7652&pathrev=7653 r7653] - fixed)
* нарушение существующего поведения команд ([https://github.com/OpenKore/openkore/commit/6efaf8bc047ee19726d7ea5e7964a69afef46e7d r7653] - исправлено)
* obscure and not properly tested (unittests are necessary) changes of core systems, which may break many random things ([http://forums.openkore.com/viewtopic.php?t=10700 map instances] - fixed; [http://forums.openkore.com/viewtopic.php?t=17888 line of sight])
* неясные и не должным образом протестированные (необходимы юнит-тесты) изменения основных систем, которые могут привести к поломке многих случайных вещей ([http://forums.openkore.com/viewtopic.php?t=10700 экземпляры карт] - исправлено; [http://forums.openkore.com/viewtopic.php?t=17888 LOS (прямая видимость)])


Compatibility workaround examples:
Примеры совместимости:
* [[storageAuto_npc_type]] would tell you if you're trying to use deprecated (and removed) '''0''' value
* [[storageAuto_npc_type]] сообщит вам, пытаетесь ли вы использовать устаревшее (и удаленное) значение '' '0' ''


== Behaviour changes ==
== Изменения в поведении ==


While some changes may not really break compatibility, they may introduce some unwanted behaviour changes. Treat this situation the same as compatibility changes.
Хотя некоторые изменения не нарушают совместимость, они могут вносить нежелательные изменения в поведении. Относитесь к этой ситуации так же, как к изменениям совместимости.


Unjustified behaviour breaking examples:
Неоправданные примеры нарушения поведения:
* removing secure-by-default behaviour which many users rely on, making it a non-default option when motives for such behaviour in the first place weren't changed ([http://openkore.svn.sourceforge.net/viewvc/openkore/openkore/trunk/src/AI/CoreLogic.pm?r1=8118&r2=8117&pathrev=8118 r8118], [[shopAuto_open]] and [[lockMap]] - fixed)
* удаление безопасного поведения по умолчанию, на которое полагаются многие пользователи. Сделать параметром не по умолчанию, хотя поведение не изменились. ([https://github.com/OpenKore/openkore/commit/cf02500cf8c0f6102f278c92c09cfc9970832173#diff-69a374805209b65ae18c8f2595a46926 r8118], [[shopAuto_open]] и [[lockMap]] - исправлено)


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


Generally, new features and names should follow the general ideas of naming of existing stuff; be guessable so you don't have to look documentation up every time you're need them; and reflect what named features actually do.
Как правило, новые функции и имена должны следовать общим идеям наименования существующих вещей; они должны быть интуитивно понятными, чтобы другим разработчикам не приходилось каждый раз искать документацию; и отражать суть функции.


Bad examples:
Плохие примеры:
* introcuding contradiction in naming of the same thing across different features (''unknown_09A1''/''sync_received_characters''/''sync_received_characters_09A1'', ''received_characters_info''/''characters_slots_info'' for the same packets in different serverTypes, and subsequent XKore "fixes" which broke all serverTypes except the one being fixed; ''skill_post_delay'' packet was added in ''ServerType0'', leaving already existing ''skill_postdelay'' in ''kRO'' as is); '''for packets and other things with native identifiers always grep all source to find out how it's already called, and make one common name for it'''
* противоречие в наименовании одной и той же вещи в разных функциях (<code>unknown_09A1</code> / <code>sync_received_characters</code> / <code>sync_received_characters_09A1</code>, <code>receive_characters_info</code> / <code>characters_slots_info</code> для одних и тех же пакетов в разных serverTypes) и последующие "исправления" XKore, которые сломали все serverTypes, за исключением того, который был исправлен; пакет <code>skill_post_delay</code> был добавлен в ''serverType0'', оставив существующий <code>skill_postdelay</code> в ''kRO'' без изменения); '''для пакетов и прочего с известными идентификаторами всегда выполняйте поиск по всему коду, чтобы выяснить, как он уже вызывался, и сделайте для него одно общее имя'''
* total mismatch between name and feature ([[teleportAuto_search]] isn't for teleporting and won't really do any search by itself; <code>buy_bulk_vender</code> packet is not for buying, but for selling items)
* hijacking of names in existing name theme ([[pl]], [[ml]], [[vl]] etc listing commands, but [[cl]] clear log - fixed)
* mismatch in naming scope ([[shop_LockOnly]] affects only shopAuto_* options, compare with [[shop_random]] which affects both auto and manually opened shops - fixed)
* not following general name uppercasing theme ([[shop_LockOnly]], while all other options use lowercase letter after an underscore; <code>GANSI_RANK</code> and <code>ISVR_DISCONNECT</code> packets, while all other packets prefer lowercase names - fixed)
* not following similar name theme across different features ([[shop_LockOnly]], while there already were [[inLockOnly]], [[attackAuto_inLockOnly]], [[avoidList_inLockOnly]] - fixed)
* using random abbreviations, especially in a set where no other member is abbreviated (<code>Glt. Cross</code> job name), especially when it's used in configurations (such names are usually unguessable unless you look them up); our own conventional abbreviations, like LOS, KS, Dmg are fine to stick to. If you name doesn't fit into some interface's display, it's a problem of interface only and should be dealt in it (and we have many different ones) - names shouldn't be distorted just because of some interface


If you're unsure of how to name your new options or other stuff, just ask at [http://forums.openkore.com/viewforum.php?f=37 forums] for opinions.
* полное несоответствие между именем и функцией ([[teleportAuto_search]] используется не для телепортации и не будет выполнять какой-либо автоматический поиск; пакет <code>buy_bulk_vender</code> предназначен не для покупки, а для продажи предметов)


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


K&R style, with opening brace on the same line with all declarations.
* несоответствие в области именования ([[shop_LockOnly]] влияет только на параметры shopAuto_*, сравните с [[shop_random]], которое влияет как на автоматические, так и на открытые вручную магазины - исправлено)


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.
* несоответствие регистра символов в названии переменных ([[shop_LockOnly]]], в то время как все другие опции используют строчные буквы после подчеркивания; пакеты <code>GANSI_RANK</code> и <code>ISVR_DISCONNECT</code>, тогда как все другие пакеты используют строчные имена - исправлено)


* несоответствие узнаваемости имени в разных функциях ([[shop_LockOnly]], хотя уже были [[inLockOnly]], [[attackAuto_inLockOnly]], [[avoList_inLockOnly]] - исправлено)
* использование случайных сокращений, особенно в списке, где ни один другой элемент не использует сокращенным (<code>Glt. Cross</code> имя профессии), особенно когда он используется в настройках (такие имена обычно не угадываемые, если Вы не просматриваете исходники); наши собственные условные обозначения, такие как LOS, KS, Dmg, лучше придерживаться. Если Ваше имя не вписывается в отображение какого-либо интерфейса, это проблема только интерфейса и её следует решать именно в интерфейсе (есть несколько решений) - имена не должны искажаться из-за какого-либо интерфейса
Если Вы не знаете, как назвать свои новые опции или что-то ещё, просто спросите на [http://forums.openkore.com/viewforum.php?f=37 форуме] или в [https://webchat.freenode.net/?channels=openkore чате]
== форматирование ==
Стиль K&R (Kernighan & Ritchie), скобка остаётся на той же строке, где располагается часть кода, к которой она (скобка) принадлежит.
В качестве отступов используются TABs. Не используйте TABs для других целей. Для TAB не определен размер столбца, каждый разработчик может иметь свои предпочтения, уважайте это.
<pre>
<pre>
sub test {
sub test {
Строка 66: Строка 70:
<TAB> }
<TAB> }
<TAB> $twenty = 20;
<TAB> $twenty = 20;
<TAB> $ten    = 10; # use spaces if you want to align (not indent) code like this for some reason
<TAB> $ten    = 10; # используйте пробелы если вы хотите выровнять код (не отступ) подобный этому
}
}
</pre>
</pre>
Строка 72: Строка 76:
[[File:TabsSpacesBoth.png]]
[[File:TabsSpacesBoth.png]]


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


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


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


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


Packet "names": underscore_separated_words
Пакет "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''
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). ''Подчеркивание также используется в блоках конфига''


== 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
Ключевые слова: 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 <code>Glt. Cross</code>, as just renaming them would break existing users' configurations.
Вы не должны сейчас просто идти и «исправлять» имена для [[teleportAuto_search]] и <code>Glt. Cross</code>, так как простое их переименование нарушит настройки существующих пользователей.

Текущая версия от 16:14, 22 января 2019

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

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