AMX MOD X
Четверг, 28.03.2024, 17:55:55



Приветствую Вас Гость | RSS
[ Главная ] [ Удобочитаемость и понятность кода - AMX Mod X Форум ] [ Регистрация ] [ Вход ]
[ Новые сообщения · Участники · Правила форума · Поиск · RSS ]

Вниманию участников! Данный форум теперь является архивом и вскором времени здесь нельзя будет создавать новых тем! Просьба всем для общения и создания новых тем перейти на наш новый форум: http://amxmodx.su/

  • Страница 1 из 1
  • 1
Модератор форума: slogic, AlMod  
AMX Mod X Форум » Скриптинг » Полезная информация » Удобочитаемость и понятность кода (Как эффективно читать код плагинов и не только)
Удобочитаемость и понятность кода
VENДата: Воскресенье, 16.03.2008, 19:14:44 | Сообщение # 1
AMXX-Скриптинг-Эксперт
Группа: Админы
Сообщений: 1892
Репутация: 45
Статус: Не в сети
Один из скриптеров, как-то раз указал на отсутсвие комментариев в коде моих плагинов. Что ж, замечание вполне резонное. Да, наверное, всилу временного фактора (хотя, и не только) у меня нет четко выработанной привычки комментировать код моих плагинов. Особенно это касается русского языка. А комментарии на любом другом языке для большинства русскоязычных пользователей не будут достаточно полезны.

Но это не значит, что для меня не важна понятность и удобочитаемость моего кода. Напротив - готовясь писать плагин, я всегда начинаю с планирования структуры кода и стиля именования элементов языка - очевидно, что это ключевые моменты, помогающие всем (и мне в том числе, что тоже не маловажно) впоследствие понимать мой код.

Иногда я все же вставляю т.н. "критические" комментарии, например, когда именование элементов языка не обеспечивает достаточного понимания, или когда действия, осуществляющиеся в коде, на первый взгляд кажутся чуть ли не абсурдными, но имеют под собой очень веское обоснование, что порой довольно сложно заметить.

Вернувшись к теме о именовании элементов языка, замечу, что зачастую я стараюсь данным мной элементу именем полностью описать его предназначение и/или функции, поэтому вставлять дополнительный комментарий кажется мне необоснованым. Для примера рассмотрим часть кода данного плагина.

Code
#define MAX_CLIENTS 32

new Float:g_fPlayerReloadEndGameTime[MAX_CLIENTS + 1]
Что мы можем сказать о этих двух строках, даже не читая остальной код плагина? Начнем по порядку.

Создаем макроконстанту, очевидно, определяющую абсолютный максимум клиентов - 32.

По следующей строке кода можно судить о многом:

  • 1. Элемент "new" говорит о том, что мы "создаем" переменную.
  • 2. Т.к. присвоения конкретного значения не происходит, значение переменной инициализируется как "ноль".
  • 3. Т.к. после элемента "new" отсутствует атрибут "const", можно судить о том, что впоследствии переменная может изменять свое значение.
  • 4. Префикс "g_", говорит нам о том, что переменная создается в глобальном пространстве, т.е. переменная является глобальной, т.о. будет доступна из любой части кода.
  • 5. Используя квадратные скобки, мы задаем размерность, значит, это не просто одиночная переменная, а массив переменных, имеющий размерность 32 + 1 == 33 - таково общее количество элементов данного массива (от 0-ого элемента до 32-ого - всего 33).
  • 6. Тэг Float говорит о том, что переменные массива являются дробными.
  • 7. Т.к. впоследствии при использовании данного массива в коде тэг Float фигурировать уже не будет, к имени массива мы добавляем символ "f" (это один из примеров т.н. венгерской нотации, широко использующейся программистами всего мира), что в любой момент укажет нам на то, что данный массив имеет тип Float.
  • 8. Теперь откинем все вспомогательные элементы языка на данной строке, а также префиксы венгерской нотации, и мы увидем основу имени "PlayerReloadEndGameTime", скорее всего, речь идет о игровом времени момента конца перезарядки, очевидно, оружия игрока.
  • 9. Т.к. речь идет о массиве, можно догадаться о том, что каждому игроку соответствует своя ячейка массива. Т.к. каждый игрок имеет свой индекс от 1 до 32 (абсолютный максимум), чем не обделен и наш массив, проводим простую аналогию: игроку с определенным индексом соответствует тот же индекс массива, а следовательно и ячейка массива, она же "элемент". При этом нулевая ячейка массива остается неиспользуемой, поэтому наш массив и имеет размерность 33, а на не 32, как в случае с игроками.

Также в коде можно увидеть функции, например: MsgBarTime и fwMsgWeaponList. Первая из которых используется для отсылки клиенту сообщения (Msg -> message, сообщение), имеющего название "BarTime". Вторая - это forward (fw) функция, т.е. функция, вызывающаяся в момент, когда мод отсылает сообщение (Msg) с именем "WeaponList".

И так далее можно разбирать код по полочкам. Таким образом, чтобы эффективно читать код, необходимо в первую очередь разобраться в фундаментальных основах AMX Mod X скриптинга, в том числе в типах данных и прототипах функций. Также будет нисколько не лишним освоить венгерскую нотацию и общие принципы AMX Mod X и его скриптинга. Но и этого недостаточно для т.н. "полного понимания картины". Важным фактором здесь также будут знания внутренного устройства и функционирования: AMX Mod X, Metamod, а также самой системы сервер-клиент вцелом.

P.S.: Знаю, что тема раскрыта далеко не полностью, но все же лучше, чем ничего.

 
DaTaДата: Воскресенье, 16.03.2008, 19:43:28 | Сообщение # 2
Генерал-полковник
Группа: Cупер-модеры
Сообщений: 1025
Репутация: 16
Статус: Не в сети
Лично моя проблема в том, что я не знаю английский язык совершенно и это меня очень ограничивает в моих возможностях(читать hlsdk, например). Переводчик мне тоже не помогает понять английский, т.к. переводит криво :(
 
VENДата: Воскресенье, 16.03.2008, 19:55:18 | Сообщение # 3
AMXX-Скриптинг-Эксперт
Группа: Админы
Сообщений: 1892
Репутация: 45
Статус: Не в сети
Ну, для таких, как ты, существует данный форум, так что многие ответы можно найти и/или получить прямо тут. Важно, кстати, еще правильно задавать вопросы - как известно "в правильно поставленном вопросе содержится половина ответа".
 
DaTaДата: Воскресенье, 16.03.2008, 20:01:00 | Сообщение # 4
Генерал-полковник
Группа: Cупер-модеры
Сообщений: 1025
Репутация: 16
Статус: Не в сети
Если я создам тему с просьбой разобрать какой-то файл с hlsdk ты поможешь? %)
А если 100 файлов? :(
 
VENДата: Воскресенье, 16.03.2008, 20:22:20 | Сообщение # 5
AMXX-Скриптинг-Эксперт
Группа: Админы
Сообщений: 1892
Репутация: 45
Статус: Не в сети
Может и помогу, может кто другой поможет - это же форум, никогда не знаешь, каков будет ответ. Но мы плавно отклонились от темы...
 
max_ripДата: Понедельник, 17.03.2008, 18:49:08 | Сообщение # 6
Подполковник
Группа: Пользователи
Сообщений: 147
Репутация: 0
Статус: Не в сети
да все, что написал VEN - это хороший тон, но бывает пишется плагин на коленке, увы в такие моменты бывает трудно сразу все описать как положено.
Во многом меня, да и большинство других, ограничивает знание английского, да я могу его читать, понимать смысл написанного, кое где пользоваться переводчиками, но идея в большинстве случаев доходит до меня. Но вот обратно - увы знанйи не хватает, да и самих слов толком не знаю. Увы упущения в школьной программе дают знать о себе до сих пор. Как поступать в таких случаях, иногда и такие не сильно образованные головы рождают просто гениальные идеи.
 
mozartДата: Среда, 19.11.2008, 23:58:11 | Сообщение # 7
Лейтенант
Группа: Пользователи
Сообщений: 46
Репутация: 0
Статус: Не в сети
у меня нао6орот про6лем с я3ыком не во3никает я в3ял и читал все скрипты которые нашел на компе 3е суток подряд
сна4ала выделились 6локи функций потом еще кое что причем я не читал НИ ЕДИНОЙ инструкции а потом простенький плагин тоже смог написать. конечно дело не только в я3ыке . я пишу скрипты в основном для консоли кс а тут решил и амхх подучить
в целом нехватает описания не только функция а 6а3овых функций
ну скажем
set_user_rendering
fakemeta функции и самых популярных - то есть не все описания можно найти
 
DaTaДата: Четверг, 20.11.2008, 01:13:24 | Сообщение # 8
Генерал-полковник
Группа: Cупер-модеры
Сообщений: 1025
Репутация: 16
Статус: Не в сети
Quote (mozart)
в целом нехватает описания не только функция а 6а3овых функций
ну скажем
set_user_rendering
fakemeta функции и самых популярных - то есть не все описания можно найти

Для этого и создан форум, задавай вопросы в соответствующих разделах - на них ответят.
 
predatorДата: Четверг, 20.11.2008, 11:31:27 | Сообщение # 9
Лейтенант
Группа: Пользователи
Сообщений: 54
Репутация: 5
Статус: Не в сети
Удобочитаемость приходит с опытом.

Визуализация:
- размещение кода на экране (табуляторы)
- оформление строк (выделение знаков пробелами, выравнивание элементов строк)
- оформление функций

Именование переменных:
- как уже сказано "венгерка" идеально подходит

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

Стиль
- стиль написания тоже очень важен, но тут уже важно не только знание языка но и хорошее знание области применения, как пример изящный способ построчного чтения строк из cfg файла:

Quote

// Чтение из файла filename строки string длиной len
while ( read_file ( filename, pos++, string, sizeof ( string ) - 1, len ) )
{
// Если строка начинается не со знака ";" разбиваем строку на 3 параметра param, param2, paramN и если разбивка произошла удачно - выполняем тело условия
if ( string[0] != ';' && parse ( string, param1, sizeof ( param1 ) - 1, param2, sizeof ( param2 ) - 1, paramN, sizeof ( paramN ) - 1) )
{
// Обработка параметров: param1, param2, paramN
}
}

ну ведь красотища :) по сравнению с организацией того же самого через цикл с fopen ...

в принципе это оценить смогут в основном только программеры...

 
DaTaДата: Четверг, 20.11.2008, 12:25:22 | Сообщение # 10
Генерал-полковник
Группа: Cупер-модеры
Сообщений: 1025
Репутация: 16
Статус: Не в сети
Quote (predator)
ну ведь красотища :) по сравнению с организацией того же самого через цикл с fopen ...

fopen не открывает при каждом новом считывании файл заново(в отличии от read_file) и не ищет каждый раз нужную строчку.

Очевидные комментарии(как в коде, представленном выше) только сбивают с толку, ими не стоит злоупотреблять, но если у вас встретится такая строка

Code
player++ %=  g_maxplayers

то можно и разжевать что к чему :)
 
predatorДата: Пятница, 21.11.2008, 12:16:54 | Сообщение # 11
Лейтенант
Группа: Пользователи
Сообщений: 54
Репутация: 5
Статус: Не в сети
Quote (DaTa)

1. fopen не открывает при каждом новом считывании файл заново(в отличии от read_file) и не ищет каждый раз нужную строчку.

2. Очевидные комментарии(как в коде, представленном выше) только сбивают с толку, ими не стоит злоупотреблять, но если у вас встретится такая строка


1. Я привел пример изящной, с моей точки зрения, конструкции кода - об оптимальности и неизбыточности и слова небыло.
2. Комментарии в приведенном коде избыточны и служат только для для его понмания как можно большим числом читающих его здесь.
 
AMX Mod X Форум » Скриптинг » Полезная информация » Удобочитаемость и понятность кода (Как эффективно читать код плагинов и не только)
  • Страница 1 из 1
  • 1
Поиск:

AMX Mod X Russian Community © 2006-2024